Sphinx shows warnings for a code that imports latest version of SQLAlchemy==2.0.4

vrtareg-az commented 1 year ago

Describe the bug

When running make html on a code that imports SQLAlchemy some warnings are shown:

from sqlalchemy import ForeignKey, MetaData, UniqueConstraint, Enum, CheckConstraint
from sqlalchemy.types import JSON, LargeBinary
from sqlalchemy.orm import DeclarativeBase, relationship, Mapped, mapped_column

class Base(DeclarativeBase):
    """Base class definition based on "DeclarativeBase" type
    """
    pass

class AdminConfig(Base):
    """Class defining "admin_config" table
    """
    __tablename__='admin_config'

Warnings

Windows

Running Sphinx v5.3.0
loading pickled environment... failed
failed: source directory has changed
[autosummary] generating autosummary for: _middleware\models.Base.rst, _middleware\models.Project.rst, _middleware\models.rst, index.rst, middleware.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 5 source files that are out of date
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [100%] middleware
WARNING: Failed guarded type import with ImportError("cannot import name '_RegistryType' from 'sqlalchemy.orm._typing' (C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\sqlalchemy\\orm\\_typing.py)")
WARNING: Failed guarded type import with ImportError("cannot import name '_RegistryType' from 'sqlalchemy.orm._typing' (C:\\Users\\xxx\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\site-packages\\sqlalchemy\\orm\\_typing.py)")
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] middleware
C:\Work\BitBucket\xxx\middleware\models.py:docstring of models.Base:1: WARNING: undefined label: 'orm_declarative_metadata'
C:\Work\BitBucket\xxx\middleware\models.py:docstring of models.Project:1: WARNING: undefined label: 'orm_declarative_metadata'
generating indices... genindex py-modindex done
highlighting module code... [100%] models
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 4 warnings.

The HTML pages are in build\html.

Ubuntu

Running Sphinx v6.1.3
loading pickled environment... done
[autosummary] generating autosummary for: _middleware/models.Base.rst, _middleware/models.Project.rst, _middleware/models.rst, index.rst, middleware.rst
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 3 changed, 0 removed
reading sources... [100%] _middleware/models.Project
WARNING: Failed guarded type import with ImportError("cannot import name '_RegistryType' from 'sqlalchemy.orm._typing' (/usr/local/lib/python3.10/dist-packages/sqlalchemy/orm/_typing.py)")
WARNING: Failed guarded type import with ImportError("cannot import name '_RegistryType' from 'sqlalchemy.orm._typing' (/usr/local/lib/python3.10/dist-packages/sqlalchemy/orm/_typing.py)")
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] middleware
/mnt/c/Work/BitBucket/xxx/middleware/models.py:docstring of models.Base:1: WARNING: undefined label: 'orm_declarative_metadata'
/mnt/c/Work/BitBucket/xxx/middleware/models.py:docstring of models.Project:1: WARNING: undefined label: 'orm_declarative_metadata'
generating indices... genindex py-modindex done
highlighting module code... [100%] sqlalchemy.sql.schema
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 4 warnings.

The HTML pages are in build/html.

How to Reproduce

Create folder xxx Create folders xxx/docs and xxx/middleware

file xxx/middleware/models.py

import enum
from typing import Optional
from datetime import datetime
from sqlalchemy import ForeignKey, MetaData, UniqueConstraint, Enum, CheckConstraint
from sqlalchemy.types import JSON, LargeBinary
from sqlalchemy.orm import DeclarativeBase, relationship, Mapped, mapped_column

class Base(DeclarativeBase):
    """Base class definition based on "DeclarativeBase" type
    """
    pass

class Project(Base):
    """Class defining "project" table
    """
    __tablename__ = 'project'

    project_id : Mapped[int] = mapped_column(primary_key=True)
    project_name : Mapped[str] = mapped_column(unique=True)
    business_unit_id : Mapped[int] = mapped_column(ForeignKey('business_unit.business_unit_id'))
    active : Mapped[bool] = mapped_column(index=True)
    description : Mapped[Optional[str]]
    md_created_by : Mapped[int] = mapped_column(ForeignKey('user.user_id'))
    md_created_at : Mapped[datetime]
    md_last_updated_by : Mapped[Optional[int]] = mapped_column(ForeignKey('user.user_id'))
    md_last_updated_at : Mapped[Optional[datetime]]
    #md_checksum = mapped_column(LargeBinary)

    project_user_map : Mapped['ProjectUserMap'] = relationship(back_populates='project')
    business_unit : Mapped['BusinessUnit'] = relationship(back_populates='project')
    project_service_map : Mapped['ProjectServiceMap'] = relationship(back_populates='project')

    ##task_execution : Mapped['TaskExecution'] = relationship(back_populates='project')
    ##connection : Mapped['Connection'] = relationship(back_populates='project')
    ##project_history : Mapped['ProjectHistory'] = relationship(back_populates='project')

    def __repr__(self) -> str:
        return f'Project(project_id={self.project_id!r}, project_name={self.project_name!r}, business_unit={self.business_unit!r}, active={self.active!r}, description={self.description!r}, md_created_by={self.md_created_by!r}, md_created_at={self.md_created_at!r}, md_last_updated_by={self.md_last_updated_by!r}, md_last_updated_at={self.md_last_updated_at!r})'

file docs/requirements.txt

sphinx
sphinx-rtd-theme
pydata-sphinx-theme
sphinx-autodoc-typehints
nbsphinx
ipython
SQLAlchemy

file docs/source/conf.py

# Configuration file for the Sphinx documentation builder.
#

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
import sys

sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('../../middleware/'))

# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'XXX'
copyright = 'XXX'
author = 'XXX'

# The full version, including alpha/beta/rc tags
release = '0.1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc',  # Core Sphinx library for auto html doc generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables for modules/classes/methods etc
    'sphinx.ext.intersphinx',  # Link to other project's documentation (see mapping below)
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',  # Add a link to the Python source code for classes, functions etc.
    'sphinx_autodoc_typehints', # Automatically document param types (less noise in class signature)
    'sphinx.ext.napoleon',
    'IPython.sphinxext.ipython_console_highlighting'
]

# Extension Settings
autosummary_generate = True  # Turn on sphinx.ext.autosummary
html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
#nbsphinx_allow_errors = True  # Continue through Jupyter errors
#autodoc_typehints = "description" # Sphinx-native method. Not as good as sphinx_autodoc_typehints
add_module_names = False # Remove namespaces from class/method signatures
napoleon_google_docstring = False
napoleon_use_param = False
napoleon_use_ivar = True

templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

# html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

file docs/Makfile

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

file docs/make.bat

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
    set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
    echo.
    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
    echo.installed, then set the SPHINXBUILD environment variable to point
    echo.to the full path of the 'sphinx-build' executable. Alternatively you
    echo.may add the Sphinx directory to PATH.
    echo.
    echo.If you don't have Sphinx installed, grab it from
    echo.https://www.sphinx-doc.org/
    exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd

file docs/index.rst

.. Project Control Plane documentation master file, created by
   sphinx-quickstart on Wed Feb 22 13:58:59 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
.. toctree::
   :hidden:

   Home page <self>
   Models Reference <_middleware/models>

Welcome to Project Control Plane's documentation!
======================================================

This is Project Control Plane documentation build using Sphinx

file docs/middleware.rst

..
   DO NOT DELETE THIS FILE! It contains the all-important `.. autosummary::` directive with `:recursive:` option, without
   which API documentation wouldn't get extracted from docstrings by the `sphinx.ext.autosummary` engine. It is hidden 
   (not declared in any toctree) to remove an unnecessary intermediate page; index.rst instead points directly to the 
   package page. DO NOT REMOVE THIS FILE!

:orphan:

.. autosummary::
   :toctree: _middleware
   :template: custom-module-template.rst

   models

files docs/_templates/custom-class-template.rst and docs/_templates/custom-module-template.rst are taken from https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion/tree/master/docs/_templates

Environment Information

# Windows 10
Platform:              win32; (Windows-10-10.0.19044-SP0)
Python version:        3.11.2 (tags/v3.11.2:878ead1, Feb  7 2023, 16:38:35) [MSC v.1934 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        5.3.0
Docutils version:      0.17.1
Jinja2 version:        3.1.2

# Ubuntu 22.04 (WSL on windows)
Platform:              linux; (Linux-5.15.79.1-microsoft-standard-WSL2-x86_64-with-glibc2.35)
Python version:        3.10.6 (main, Nov 14 2022, 16:10:14) [GCC 11.3.0])
Python implementation: CPython
Sphinx version:        6.1.3
Docutils version:      0.18.1
Jinja2 version:        3.0.3
Pygments version:      2.14.0

Sphinx extensions

extensions = [
    'sphinx.ext.autodoc',  # Core Sphinx library for auto html doc generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables for modules/classes/methods etc
    'sphinx.ext.intersphinx',  # Link to other project's documentation (see mapping below)
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',  # Add a link to the Python source code for classes, functions etc.
    'sphinx_autodoc_typehints', # Automatically document param types (less noise in class signature)
    'sphinx.ext.napoleon',
    'IPython.sphinxext.ipython_console_highlighting'
]

Additional context

No response

hojo0590 commented 10 months ago

Stumbled upon this with a different problem. Probably it caused this one in sphinx-autodoc-typehints?

Cielquan commented 9 months ago

I also get this warning in rstcheck-core with pydantic:

WARNING: Failed guarded type import with ImportError("cannot import name 'AbstractSetIntStr' from 'pydantic._internal._utils' (/home/runner/work/rstcheck-core/rstcheck-core/.tox/docs/lib/python3.11/site-packages/pydantic/_internal/_utils.py)")

Ci run: https://github.com/rstcheck/rstcheck-core/actions/runs/6130583383/job/16639807942?pr=60#step:11:558

barik94 commented 8 months ago

@hojo0590 @Cielquan did you find solution to resolve this problem "cannot import name 'AbstractSetIntStr' from 'pydantic._internal._utils'" ?

behai-nguyen commented 2 months ago

Thank you for reporting this. I have same warning, too:

F:\bh_database\docs\docstring of bh_database.core.Base.metadata:6: WARNING: undefined label: 'orm_declarative_metadata'

SQLAlchemy version 2.0.29 -- I have this warning after replacing declarative_base with DeclarativeBase.

New code that causes the above warning:

from sqlalchemy.orm import (
    sessionmaker, 
    scoped_session,
    DeclarativeBase,
    close_all_sessions,
    Query,
)
from sqlalchemy.orm.decl_api import DeclarativeMeta

class Base(DeclarativeBase):
    metaclass=DeclarativeMeta

Previous code that do not cause the above warning:

from sqlalchemy.orm import (
    sessionmaker, 
    scoped_session,
    declarative_base,
    close_all_sessions,
    Query,
)
from sqlalchemy.orm.decl_api import DeclarativeMeta

#: 
Base = declarative_base(metaclass=DeclarativeMeta)

anton-daneyko-ultramarin commented 2 months ago

I get a similar error:

Warning, treated as error:
Failed guarded type import with ImportError("cannot import name 'AbstractSetIntStr' from 'pydantic._internal._utils' (/Users/ant/opt/miniconda3/envs/apa-proxy/lib/python3.12/site-packages/pydantic/_internal/_utils.py)")

Pinning the version to <1.15 did help.

sphinx-doc / sphinx