Packaging and Environments

An absolute import spells out the full dotted path from an import root, such as from app.core import config. An explicit relative import starts with dots that count outward from the importing module's own package: from . import config.

Two modules import each other. Python began running the first one, cached it half-finished, and the second one asked it for a name that has not been defined yet, so the name lookup fails.

Python sets the module global name to "main" only in the file the interpreter was started with; an imported module gets its dotted import name instead. The guarded block therefore runs on direct execution and is skipped on import.

A module is one importable unit of code, usually a single .py file. A package is a module that can also contain submodules: a directory whose init.py file is executed as the package's own body when it is first imported.

Since Python 3.3 (PEP 420) a directory with no init.py imports as an implicit namespace package: the search path held only matching directories, so Python builds a package that runs no code and whose file is None.

pip install -e . installs the project in editable mode: site-packages receives a pointer back to your working source tree instead of a copy of it, so a source edit takes effect on the next interpreter start without reinstalling.

A bare pip is a script on PATH whose shebang points at whichever interpreter installed it, so PATH order decides where the install lands. python -m pip runs the pip belonging to the interpreter you just named, so the packages land where that interpreter imports from.

pyproject.toml declares abstract dependencies: the ranges a package can work with, re-resolved at install time. A pinned requirements.txt records one concrete resolution so a particular deployment installs exactly the same versions every time.

Besides a name from an index, pip install accepts a path to a project directory, wheel or sdist, a direct URL, a version-control reference such as git+https at a tag or commit, and -r to read requirement lines from a file.

It owns the project end to end: it creates and syncs a project-local virtual environment, resolves the declared dependencies into a lock file, and runs commands inside that environment. pip and venv each do one piece and leave the wiring to you.

It declares a console command. At install time the installer generates a small wrapper in the environment's script directory that imports the named module and calls the named function, so typing the command runs your code.

It installs mypkg itself plus the optional dependency set named redis. That set is declared in the project's pyproject.toml under the [project.optional-dependencies] table, where each key is an extra name and its value is a list of requirement strings.

Because no prebuilt wheel matched this machine's interpreter version, ABI and platform, pip fell back to the source archive. Compiling it needs a C compiler and linker, CPython's development headers (Python.h), and the project's declared build backend.

Put the file inside the importable package directory and declare it as package data in your build backend's configuration. Setuptools needs a package-data entry, or include-package-data together with MANIFEST.in; hatchling and flit ship non-code files under the package by default.

A single leading underscore marks a name as internal: not part of the public API and free to change without notice. It is a convention, not enforcement — outside code can still import and call it.

Python's default filters ignore DeprecationWarning unless it is attributed to the main module, so end users are not flooded with warnings about libraries they did not write. Surface them with -W default::DeprecationWarning, PYTHONWARNINGS, or -X dev.

It declares the interpreter range the distribution supports, and lands in the built metadata as Requires-Python. An installer filters out releases whose range excludes the running interpreter and resolves to the newest release that still allows it.

Compare sys.version_info against a plain tuple, as in sys.version_info >= (3, 12), and put the newer-only import or branch inside that guard. Never parse the sys.version string; tuple comparison is exact, cheap and unambiguous.

Promote the category to an error, but scope it. Run the suite with -W ignore::DeprecationWarning -W error::DeprecationWarning:yourpackage, or set PYTHONWARNINGS to the same spec: the later filter is checked first, so only your own code is fatal.

Do the diagnosis on the interpreter you are leaving: PEP 387 guarantees two releases of DeprecationWarning, but it is filtered out by default. Surface it, diff your imports against the target's sys.stdlib_module_names, then replace modules one at a time before bumping the interpreter.