Environment Structure

[MarcBarlett]

Alembic init creates the directory structure:

yourproject/
    alembic/
        env.py
        README
        script.py.mako
        versions/

Since the main directory un is "alembic" it conflicts with Import alembic commands and results in ModuleNotFoundError: No module...

Am I missing something basic? other than renaming the directory, but shouldn't the default created directory not be in conflict?

[zzzeek]

I dont see this error happening in normal cases for three separate reasons, any one of them is enough to prevent the error and all three are true by default:

1. the name "alembic" is not hardcoded, you have to give it the location where you want alembic to be installed.
2. alembic does not put an __init__.py file by default in the generated location, so it will not be recognized as a path in any case
3. Python does not include "." in sys.path by default.

[classic@framework tmp]$ python -m venv .venv
[classic@framework tmp]$ source .venv/bin/activate

# let's use the potentially problematic "alembic" name
(.venv) [classic@framework tmp]$ pip install alembic
Collecting alembic  ...
Successfully installed Mako-1.3.10 MarkupSafe-3.0.2 SQLAlchemy-2.0.40 alembic-1.15.2 greenlet-3.2.2 typing-extensions-4.13.2

(.venv) [classic@framework tmp]$ alembic init alembic
  Creating directory '/home/classic/tmp/alembic' ...  done
  Creating directory '/home/classic/tmp/alembic/versions' ...  done
  Generating /home/classic/tmp/alembic/README ...  done
  Generating /home/classic/tmp/alembic.ini ...  done
  Generating /home/classic/tmp/alembic/env.py ...  done
  Generating /home/classic/tmp/alembic/script.py.mako ...  done
  Please edit configuration/connection/logging settings in '/home/classic/tmp/alembic.ini' before proceeding.

# command is fine
(.venv) [classic@framework tmp]$ alembic history

# try with sys.path including dot
# command is fine
$ PYTHONPATH=. alembic history

# add __init__.py
(.venv) [classic@framework tmp]$ touch alembic/__init__.py

# NOW it breaks *if* you also include non standard sys.path
(.venv) [classic@framework tmp]$ PYTHONPATH=. alembic history
Traceback (most recent call last):
  File "/home/classic/tmp/.venv/bin/alembic", line 5, in <module>
    from alembic.config import main
ModuleNotFoundError: No module named 'alembic.config'

# but without non-standard sys.path, *still* works
(.venv) [classic@framework tmp]$ alembic history

[MarcBarlett]

Those are fair observations.
I do have an init.py although I don't recall why and removing it might make my life easier.
Also I think VSCode might add '.' to sys.path

[zzzeek]

where the docs can be changed is that alembic is usually not in the root of the project, it's usually a submodule

so like this:

cd /path/to/project
alembic init --package myproject/alembic 

where --package creates that __init__.py file though it isnt usually needed unless you want to have local imports in your env.py