Snippet dependencies

drain_swamp.snippet_dependencies.__all__: tuple[str, str, str] = ("SnippetDependencies", "get_required_and_optionals", "generate_snippet")

Module’s exports

drain_swamp.snippet_dependencies._logger: logging.Logger

Module level logger

drain_swamp.snippet_dependencies.is_module_debug: bool = False

turn on/off module level log messages

class drain_swamp.snippet_dependencies.T_REQUIRED

drain_swamp.snippet_dependencies.T_REQUIRED: tuple[str, pathlib.Path] | None

Required dependency

class drain_swamp.snippet_dependencies.T_OPTIONALS

drain_swamp.snippet_dependencies.T_OPTIONALS: collections.abc.Mapping[str, pathlib.Path]

Optional dependencies

class drain_swamp.snippet_dependencies.SnippetDependencies

In pyproject.toml, dependencies can be organized in many requirements files. So the assumption dependencies are dynamic rather than static.

drain-swamp distinguishes between, and has both, dependency lock and unlock files.

Requirement files, typically with .txt extention, are replaced with: .in, .unlock, .lock, and .lnk.

The .unlock and .lock are generated, but can be manually editted.

The .lnk is created during package build process. On Windows, it’s a file copy on other platforms it’s a symlink. Python build process resolves symlinks.

A snippet is placed in section, tool.setuptools.dynamic. The snippet has both start and end tokens. No need to know the section name. The snippet contains both dependencies and optional-dependencies.

Metadata is needed to generate the snippet contents.

• (extra) folders

• required

• optionals

When dependency locked (and before refresh)

# @@@ editable
dependencies = { file = ['requirements/prod.lock'] }
optional-dependencies.pip = { file = ['requirements/pip.lock'] }
optional-dependencies.pip_tools = { file = ['requirements/pip-tools.lock'] }
optional-dependencies.dev = { file = ['requirements/dev.lock'] }
optional-dependencies.manage = { file = ['requirements/manage.lock'] }
optional-dependencies.docs = { file = ['docs/requirements.lock'] }
# @@@ end

version = {attr = 'logging_strict._version.__version__'}

When not dependency unlocked (and before refresh)

# @@@ editable
dependencies = { file = ['requirements/prod.unlock'] }
optional-dependencies.pip = { file = ['requirements/pip.unlock'] }
optional-dependencies.pip_tools = { file = ['requirements/pip-tools.unlock'] }
optional-dependencies.dev = { file = ['requirements/dev.unlock'] }
optional-dependencies.manage = { file = ['requirements/manage.unlock'] }
optional-dependencies.docs = { file = ['docs/requirements.unlock'] }
# @@@ end

version = {attr = 'logging_strict._version.__version__'}

Notice the dynamic version is not within the snippet.

Metadata section

[tool.pipenv-unlock]
folders = [
    "pip",
    "pip_tools",  # <-- underscore
    "dev",
    "manage",
    "docs",
]
required = "requirements/prod.in"
optionals = [
    'requirements/prod.in',
    'requirements/pip.in',
    'requirements/pip-tools.in',  # <-- hyphen
    'requirements/dev.in',
    'requirements/manage.in',
    'docs/requirements.in',
]

• folders

  There maybe other .in/.lock/.unlock files, such as kit.in and tox.in, these are used by tox or CI/CD. These will also need .lock and .unlock files

• required

  Even if the package has no required dependencies, .in/.lock/.unlocked files should still exist. By knowing which is the required dependencies related files, will know the others are optional, besides pins[.in|.lock|.unlock]

• optionals

  package optional-dependencies

  Can also be provided/overridden by passing in cli options

  Not allow cooresponding [.in|.lock|.unlock] will be optional-dependencies.

  File stems will have hyphens not underscore

  optional-dependencies.pip_tools = { file = ['requirements/pip-tools.unlock'] }

  The file stem is hyphen but the dependency contains underscores

Raises:

• FileNotFoundError – package required dependency file is required

drain_swamp.snippet_dependencies.generate_snippet(path_cwd, path_config, tool_name=('pipenv-unlock',), suffix_last='.lock')

Parameters:

• path_cwd (pathlib.Path) – Project base folder or test base folder

• path_config (pathlib.Path) – Path to pyproject.toml file

• tool_name (str | collections.abc.Sequence[str]) – pyproject.toml section(s) name

• suffix_last (str) – Default “.lock”. Last suffix

Returns:

Snippet content ready for coping into snippet

Return type:

str

Raises:

• AssertionError – pyproject.toml must be relative to cwd

• drain_swamp.exceptions.MissingRequirementsFoldersFiles – missing dependency support files

• ValueError –

• KeyError – pyproject section field missing. Cannot retrieve value

drain_swamp.snippet_dependencies.get_required_and_optionals(path_cwd, path_f, tool_name=('pipenv-unlock',))

Parameters:

• path_cwd (pathlib.Path) – Project base folder or test base folder

• path_f (pathlib.Path) – pyproject.toml absolute path

• tool_name (str | collections.abc.Sequence[str]) – pyproject.toml section(s) name

Returns:

All dependencies absolute Path, required dependency absolute Path or None, Mapping of target and optional dependencies absolute Path

Return type:

tuple[collections.abc.Sequence[pathlib.Path], drain_swamp.snippet_dependencies.T_REQUIRED, drain_swamp.snippet_dependencies.T_OPTIONALS]