__init__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/migrate/__init__.py
 
"""
Purpose
-------
FS-539: the ``oct migrate`` subpackage, which moves a project onto the
Option C ``.option_c/`` layout. This file is the package shell only; the
command and every migration step live in
:mod:`oct.migrate.oct_migrate`.
 
Responsibilities
----------------
- Expose ``migrate_group`` as this package's single public name.
- Resolve it LAZILY through :func:`__getattr__`, so importing
  ``oct.migrate`` alone does not import click or the migration engine.
  ``oct.cli`` does resolve it at import, to register the command.
 
Diagnostics
-----------
Domain: OCT-MIGRATE
Levels:
    L1 - errors: none raised here; the engine owns failure reporting
    L2 - (none) the lazy re-export resolves before diagnostics start
    L3 - (none) the migrate command reports in its own module
    L4 - (none)
 
Contracts
---------
- Import-time side effects: none beyond the ``_dbg`` shim. No migration
  submodule is imported until an attribute is requested.
- Emits no ``_dbg`` record: ``__getattr__`` runs during ``import oct.cli``,
  before ``oc_diagnostics.init()``, so a record here printed the "called
  before init()" RuntimeWarning on every oct invocation (plan 263's rule
  for lazy package roots; found again by the chart C runtime trace,
  2026-09-27).
- Any name other than ``migrate_group`` raises ``AttributeError``, so a
  typo fails loudly instead of returning ``None``.
- ``__all__`` and :func:`__getattr__` must agree; a name added to one
  without the other is unreachable or undeclared.
 
Dependencies
------------
- oct.migrate.oct_migrate (lazy; the migrate command, resolved inside __getattr__)
- oct.core.diagnostics (_dbg structured logger, imported but not called)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Plan 263: its lazy __getattr__ resolves during `import oct.cli`, before init(), so any _dbg call here would run before oc_diagnostics.init() and add a RuntimeWarning to every oct invocation"
from oct.core.diagnostics import _dbg
 
__all__ = ["migrate_group"]
 
 
def __getattr__(name: str):
    """Resolve ``migrate_group`` on first access; reject anything else."""
    if name == "migrate_group":
        from oct.migrate.oct_migrate import migrate as _migrate
        return _migrate
    raise AttributeError(f"module 'oct.migrate' has no attribute {name!r}")