|
| 1 | +.. default-role:: py:obj |
| 2 | + |
| 3 | +========== |
| 4 | +Public API |
| 5 | +========== |
| 6 | + |
| 7 | +This section documents the public API of `autopypath`. These are the |
| 8 | +classes, functions, and exceptions that users can import and use directly |
| 9 | +in their own code. All other internal modules and functions are considered |
| 10 | +implementation details and should not be relied upon. |
| 11 | + |
| 12 | +autopypath |
| 13 | +========== |
| 14 | + |
| 15 | +.. module:: autopypath |
| 16 | + |
| 17 | +.. code-block:: python |
| 18 | + :caption: Example usage |
| 19 | +
|
| 20 | + import autopypath |
| 21 | +
|
| 22 | +The main module that adjusts `sys.path` when imported. |
| 23 | + |
| 24 | + |
| 25 | +autopypath.debug |
| 26 | +================ |
| 27 | + |
| 28 | +.. module:: autopypath.debug |
| 29 | + |
| 30 | +.. code-block:: python |
| 31 | + :caption: Example usage |
| 32 | +
|
| 33 | + import autopypath.debug |
| 34 | +
|
| 35 | +A module that enables debug logging for `autopypath`. Importing this |
| 36 | +module sets the logging level to DEBUG, providing detailed information |
| 37 | +about the path resolution process. It also upgrades logged warnings to |
| 38 | +logged errors and raises corresponding |
| 39 | +:class:`~autopypath.exceptions.AutopypathError` exceptions. |
| 40 | + |
| 41 | +It behaves the same as the main `autopypath` module but with enhanced logging |
| 42 | +and error handling for debugging purposes. |
| 43 | + |
| 44 | + |
| 45 | +autopypath.custom |
| 46 | +================= |
| 47 | + |
| 48 | +.. module:: autopypath.custom |
| 49 | + |
| 50 | +Module for programmatic configuration of `autopypath`. |
| 51 | + |
| 52 | +configure_pypath |
| 53 | +---------------- |
| 54 | + |
| 55 | +.. py:function:: configure_pypath(*, \ |
| 56 | + repo_markers: Mapping[str, Literal['dir', 'file']] | None = None, \ |
| 57 | + paths: Sequence[Path | str] | None = None, \ |
| 58 | + load_strategy: Literal['prepend', 'prepend_highest_priority', 'replace'] | None = None, \ |
| 59 | + path_resolution_order: Sequence[Literal['manual', 'autopypath', 'pyproject']] | None = None, \ |
| 60 | + log_level: int | None = None, \ |
| 61 | + strict: bool = False) |
| 62 | +
|
| 63 | + A function that allows programmatic configuration of `autopypath` settings |
| 64 | + such as custom paths to add to `sys.path`, repository markers, and |
| 65 | + other options. This function can be used as an alternative to |
| 66 | + configuration files like `pyproject.toml` or `autopypath.toml`. |
| 67 | + |
| 68 | + When this function is called, it performs the same path resolution |
| 69 | + logic as the main `autopypath` module, adjusting :data:`sys.path` |
| 70 | + according to the provided parameters and any detected configuration files. |
| 71 | + |
| 72 | + .. code-block:: python |
| 73 | + :caption: Example usage |
| 74 | +
|
| 75 | + from autopypath.custom import configure_pypath, AutopypathError |
| 76 | +
|
| 77 | + try: |
| 78 | + configure_pypath( |
| 79 | + repo_markers={'src': 'dir', 'setup.py': 'file'}, |
| 80 | + paths=['src/utils', 'lib'], |
| 81 | + load_strategy='prepend', |
| 82 | + path_resolution_order=['manual', 'pyproject'], |
| 83 | + log_level=logging.INFO, |
| 84 | + strict=True |
| 85 | + ) |
| 86 | + except AutopypathError as e: |
| 87 | + print(f"Error configuring autopypath: {e}") |
| 88 | +
|
| 89 | + :param repo_markers: |
| 90 | + A mapping of file or directory names to their marker type used to identify the repository |
| 91 | + root. They can only be of type 'dir' or 'file' and must be names only (no paths). If :obj:`None`, |
| 92 | + the default repo markers are used. |
| 93 | + :type repo_markers: `~typing.Mapping`\[`str`, `~typing.Literal`\["dir", "file"]] | :obj:`None` |
| 94 | + |
| 95 | + :param paths: |
| 96 | + A sequence of paths to include in the :data:`sys.path`. |
| 97 | + If passed as strings, they must be formatted as POSIX-style paths (e.g., 'src/utils') and |
| 98 | + cannot be absolute paths. |
| 99 | + If passed as :class:`pathlib.Path` objects, they can be either absolute or relative paths. |
| 100 | + :type paths: `~typing.Sequence`\[`~pathlib.Path` | `str`] | :obj:`None` |
| 101 | + |
| 102 | + :param load_strategy: |
| 103 | + The strategy for loading :data:`sys.path` entries. |
| 104 | + |
| 105 | + - 'prepend': (default) Adds new paths to the front of :data:`sys.path`, but after any existing entries. |
| 106 | + - 'prepend_highest_priority': Adds new paths to the very front of :data:`sys.path`, before any existing entries. |
| 107 | + - 'replace': Clears all existing entries in :data:`sys.path` and replaces them with the new paths. |
| 108 | + :type load_strategy: `~typing.Literal`\['prepend', 'prepend_highest_priority', 'replace'] | :obj:`None` |
| 109 | + |
| 110 | + :param path_resolution_order: |
| 111 | + The order in which to resolve :data:`sys.path` sources. It specifies which configuration |
| 112 | + sources to check for paths to be added and in what order. |
| 113 | + |
| 114 | + - 'manual': The `paths` parameter passed to this function. |
| 115 | + - 'autopypath': Configuration from `autopypath.toml` files. |
| 116 | + - 'pyproject': Configuration from `pyproject.toml` files. |
| 117 | + |
| 118 | + If :obj:`None`, the default order is used: `['manual', 'autopypath', 'pyproject']` |
| 119 | + :type path_resolution_order: `~typing.Sequence`\[`~typing.Literal`\['manual', 'autopypath', 'pyproject']] | :obj:`None` |
| 120 | + |
| 121 | + :param log_level: |
| 122 | + The `logging` level to use during configuration. If :obj:`None`, the current log level is used. |
| 123 | + The logging levels are those defined in the standard `logging` module, such as |
| 124 | + `logging.DEBUG`, `logging.INFO`, `logging.WARNING`, etc. |
| 125 | + :type log_level: `int` | :obj:`None` |
| 126 | + |
| 127 | + :param strict: |
| 128 | + If `True`, raises an error for conditions that would normally only log a warning. |
| 129 | + Default is `False`. It also turns logged warnings into logged errors and raised |
| 130 | + :class:`~autopypath.custom.AutopypathError` exceptions. |
| 131 | + |
| 132 | + Conditions that normally trigger logged warnings include: |
| 133 | + |
| 134 | + - Specified paths that do not exist or cannot be resolved. |
| 135 | + :type strict: `bool` |
| 136 | + |
| 137 | + :raises AutopypathError: |
| 138 | + This is raised for various error conditions such as broken configurations; |
| 139 | + failure to find the repository root due to missing project markers; |
| 140 | + no paths being found and added to :data:`sys.path`; and other issues that |
| 141 | + represent fatal errors in the path resolution process. |
| 142 | + |
| 143 | +.. exception:: AutopypathError |
| 144 | + |
| 145 | + The main exception class for `autopypath`. |
| 146 | + |
| 147 | + This exception is made available as an import from the :mod:`autopypath.custom` |
| 148 | + module because that is where users are most likely to need to catch it when |
| 149 | + using the programmatic configuration function. |
| 150 | + |
| 151 | + Trying to import it from the main :mod:`autopypath` module or :mod:`autopypath.debug` |
| 152 | + module is generally not useful, as those modules automatically run the path |
| 153 | + resolution logic on import---before the user would have a chance to wrap the |
| 154 | + import in a `try/except` block. |
| 155 | + |
| 156 | + This exception is raised for fatal error conditions, including: |
| 157 | + |
| 158 | + - Broken configurations. |
| 159 | + - Failure to find the repository root (missing markers). |
| 160 | + - No valid paths found to add to :data:`sys.path`. |
| 161 | + - Strict mode violations (when `strict=True`). |
| 162 | + |
| 163 | +pyproject.toml and autopypath.toml Configurations and Defaults |
| 164 | +============================================================== |
| 165 | + |
| 166 | +For information on configuring `autopypath` using `pyproject.toml` or |
| 167 | +`autopypath.toml` files, and for the defaults used when no configurations |
| 168 | +are explicitly set, please refer to the :ref:`configuration section <configuration>` |
| 169 | +of the documentation. |
| 170 | + |
| 171 | +Logging |
| 172 | +======= |
| 173 | + |
| 174 | +`autopypath` uses the standard Python `logging` module to log messages |
| 175 | +about its operations. By default, it logs info, warnings and errors to help |
| 176 | +users identify potential issues with path resolution. |
| 177 | + |
| 178 | +Users can adjust the logging level by importing the :mod:`autopypath.debug` |
| 179 | +module for debug-level logging, or by using the `log_level` parameter |
| 180 | +of the :func:`configure_pypath` function for custom logging levels |
| 181 | +during programmatic configuration. |
| 182 | + |
| 183 | +The logged messages are information but not structured or machine-readable. |
| 184 | +They are intended to assist users in debugging path resolution issues |
| 185 | +and understanding how `autopypath` is modifying :data:`sys.path` but not |
| 186 | +to be parsed or processed programmatically. |
| 187 | + |
| 188 | +Exceptions |
| 189 | +========== |
| 190 | + |
| 191 | +`autopypath` raises exceptions for fatal error conditions that prevent |
| 192 | +it from successfully resolving and adjusting :data:`sys.path`. The only |
| 193 | +exception class is :class:`~autopypath.custom.AutopypathError`, which |
| 194 | +is raised for issues such as broken configurations, failure to find |
| 195 | +the repository root, no valid paths found, and strict mode violations. |
| 196 | + |
| 197 | +Users can catch these exceptions when using the :func:`configure_pypath` |
| 198 | +function for programmatic configuration. The exceptions provide |
| 199 | +meaningful error messages to help diagnose and resolve issues with |
| 200 | +path resolution. |
0 commit comments