Public API🔗

This section documents the public API of autopypath. These are the classes, functions, and exceptions that users can import and use directly in their own code. All other internal modules and functions are considered implementation details and should not be relied upon.

autopypath🔗

Example usage🔗
  import autopypath

The main module that adjusts sys.path when imported.

autopypath.debug🔗

Example usage🔗
  import autopypath.debug

A module that enables debug logging for autopypath. Importing this module sets the logging level to DEBUG, providing detailed information about the path resolution process. It also upgrades logged warnings to logged errors and raises corresponding AutopypathError exceptions.

It behaves the same as the main autopypath module but with enhanced logging and error handling for debugging purposes.

autopypath.custom🔗

Module for programmatic configuration of autopypath.

configure_pypath🔗

autopypath.custom.configure_pypath(
*,
repo_markers: Mapping[str, Literal['dir', 'file']] | None = None,
paths: Sequence[Path | str] | None = None,
load_strategy: Literal['prepend', 'prepend_highest_priority', 'replace'] | None = None,
path_resolution_order: Sequence[Literal['manual', 'autopypath', 'pyproject']] | None = None,
log_level: int | None = None,
strict: bool = False,
)[source]🔗

A function that allows programmatic configuration of autopypath settings such as custom paths to add to sys.path, repository markers, and other options. This function can be used as an alternative to configuration files like pyproject.toml or autopypath.toml.

When this function is called, it performs the same path resolution logic as the main autopypath module, adjusting sys.path according to the provided parameters and any detected configuration files.

Example usage🔗
  from autopypath.custom import configure_pypath, AutopypathError

  try:
      configure_pypath(
          repo_markers={'src': 'dir', 'setup.py': 'file'},
          paths=['src/utils', 'lib'],
          load_strategy='prepend',
          path_resolution_order=['manual', 'pyproject'],
          log_level=logging.INFO,
          strict=True
      )
  except AutopypathError as e:
      print(f"Error configuring autopypath: {e}")
Parameters:

  • repo_markers (Mapping[str, Literal[“dir”, “file”]] | None) – A mapping of file or directory names to their marker type used to identify the repository root. They can only be of type ‘dir’ or ‘file’ and must be names only (no paths). If None, the default repo markers are used.

  • paths (Sequence[Path | str] | None) – A sequence of paths to include in the sys.path. If passed as strings, they must be formatted as POSIX-style paths (e.g., ‘src/utils’) and cannot be absolute paths. If passed as pathlib.Path objects, they can be either absolute or relative paths.

  • load_strategy (Literal[‘prepend’, ‘prepend_highest_priority’, ‘replace’] | None) –

    The strategy for loading sys.path entries.

    • ’prepend’: (default) Adds new paths to the front of sys.path, but after any existing entries.

    • ’prepend_highest_priority’: Adds new paths to the very front of sys.path, before any existing entries.

    • ’replace’: Clears all existing entries in sys.path and replaces them with the new paths.

  • path_resolution_order (Sequence[Literal[‘manual’, ‘autopypath’, ‘pyproject’]] | None) –

    The order in which to resolve sys.path sources. It specifies which configuration sources to check for paths to be added and in what order.

    • ’manual’: The paths parameter passed to this function.

    • ’autopypath’: Configuration from autopypath.toml files.

    • ’pyproject’: Configuration from pyproject.toml files.

    If None, the default order is used: ['manual', 'autopypath', 'pyproject']

  • log_level (int | None) – The logging level to use during configuration. If None, the current log level is used. The logging levels are those defined in the standard logging module, such as logging.DEBUG, logging.INFO, logging.WARNING, etc.

  • strict (bool) –

    If True, raises an error for conditions that would normally only log a warning. Default is False. It also turns logged warnings into logged errors and raises AutopypathError exceptions.

    Conditions that normally trigger logged warnings include:

    • Specified paths that do not exist or cannot be resolved.

Raises:

AutopypathError – This is raised for various error conditions such as broken configurations; failure to find the repository root due to missing project markers; no paths being found and added to sys.path; and other issues that represent fatal errors in the path resolution process.

exception autopypath.custom.AutopypathError[source]🔗

The main exception class for autopypath.

This exception is made available as an import from the autopypath.custom module because that is where users are most likely to need to catch it when using the programmatic configuration function.

Trying to import it from the main autopypath module or autopypath.debug module is generally not useful, as those modules automatically run the path resolution logic on import—before the user would have a chance to wrap the import in a try/except block.

This exception is raised for fatal error conditions, including:

  • Broken configurations.

  • Failure to find the repository root (missing markers).

  • No valid paths found to add to sys.path.

  • Strict mode violations (when strict=True).

pyproject.toml and autopypath.toml Configurations and Defaults🔗

For information on configuring autopypath using pyproject.toml or autopypath.toml files, and for the defaults used when no configurations are explicitly set, please refer to the configuration section of the documentation.

Logging🔗

autopypath uses the standard Python logging module to log messages about its operations. By default, it logs info, warnings and errors to help users identify potential issues with path resolution.

Users can adjust the logging level by importing the autopypath.debug module for debug-level logging, or by using the log_level parameter of the configure_pypath() function for custom logging levels during programmatic configuration.

The logged messages are information but not structured or machine-readable. They are intended to assist users in debugging path resolution issues and understanding how autopypath is modifying sys.path but not to be parsed or processed programmatically.

Exceptions🔗

autopypath raises exceptions for fatal error conditions that prevent it from successfully resolving and adjusting sys.path. The only exception class is AutopypathError, which is raised for issues such as broken configurations, failure to find the repository root, no valid paths found, and strict mode violations.

Users can catch these exceptions when using the configure_pypath() function for programmatic configuration. The exceptions provide meaningful error messages to help diagnose and resolve issues with path resolution.