SQLAlchemy error when autogenerating documentation for database module using pdoc3

280 Views Asked by At

I'm creating documentation for a project using pydoc3 but am encountering an odd error from SQLAlchemy when running against my database module.

Background

Project layout:

PROJECT_NAME/
|-- __init__.py
|
|-- api
|   |-- main.py
|
|-- database
|   |-- __init__.py
|   |-- metadata.py
|
|   |-- methods
|       |-- __init__.py
|       |-- foo.py
|
|   |-- models
|       |-- __init__.py
|       |-- base.py
|       |-- models.py
|
| - tests
|   |-- test_this.py
...

Command to generate documentation:
Where MODULE is the name of the module...

python3 venv/bin/pdoc3 --html --output-dir docs $MODULE

The problem:

I'm able to generate documentation for each module, one at a time with no issues.
(Ex: python3 venv/bin/pdoc3 --html --output-dir docs database)

But when I try generating documentation for the entire project (MODULE='.'), I get the following error:

ImportError: Error importing 'PROJECT_NAME.database':

InvalidRequestError: Table 'FooBar' is already defined for this MetaData instance. Specify 'extend_existing=True' to redefine options and columns on an existing Table object.


What makes this error odd is that I have a full testing suite where there are no issues at all. Further, the error occurs in database.__init__.py which just doesn't make sense to me at all.


As far as a possible solution:

My thought is that my issue is coming from how I've configured my declarative base...

Content of database.__init__.py:

from .metadata import metadata
from . import methods
from . import models

Content of database.metadata.py:

from sqlalchemy import MetaData
metadata = MetaData()

Content of database.models.base.py:

from database import metadata
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base(metadata=metadata)

Content of database.models.model.py:

from database.models import Base
from sqlalchemy import Column, Integer, String

class FooBar(Base):

    __tablename__ = 'foo_bar'
    __table_args__ = {
        'comment': 'Example...'
    }

    id = Column(Integer, primary_key=True, autoincrement=True)
    name = Column(String(80), nullable=False, unique=True)

Is it possible that my models are attempted to be created twice by pydoc when called from the root?

I'm at a total loss here, not sure what resource to use to investigate further.


Update:

Following this answer as inspa, if I update the format of database.__init__.py, pdoc3 is able parse my database module, though, not database.models (which I explicitly escape, because done is better than perfect).

Revised database.__init__.py

__pdoc__ = {'models': False}

from database.metadata import metadata
from database import methods
from database import models
0

There are 0 best solutions below