Merge pull request #3 from JerilynFranz/1.0.1-release

1.0.1 release

Author: JerilynFranz

.env

@@ -2,8 +2,17 @@
 Changelog for autopypath
 ========================
 
+1.0.1 (2026-01-23)
+------------------
+
+- Updated index.rst and README.rst for clarity and consistency.
+- Removed an unused `.env` file (no functional changes).
+- Removed editor- and workspace-specific files from the source distribution.
+- Clarified the purpose of `uv.lock` for reproducible builds.
+   
 1.0.0 (2026-01-22)
 ------------------
+
 - Official release of autopypath version 1.0.0.
 - Finalized documentation and public API.
 - Added detailed examples and usage instructions.
@@ -14,10 +23,12 @@ Changelog for autopypath
 
 0.9.1 (2026-01-21)
 ------------------------
+
 - Added pre-commit Git hooks for code quality checks and formatting on commit.
 - Updated index.rst and README.rst documentation.
 - Bumped version to 0.9.1.
 
 0.9.0 (2026-01-21)
 ------------------------
+
 - Initial release for version 0.9.0 to PyPI

CHANGELOG.rst

@@ -31,20 +31,43 @@ autopypath
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff
 
+Table of Contents
+-----------------
+-  `Usage <https://python-autopypath.readthedocs.io/en/latest/usage.html>`_
+-  `Configuration <https://python-autopypath.readthedocs.io/en/latest/configuration.html>`_
+-  `Public API <https://python-autopypath.readthedocs.io/en/latest/public_api.html>`_
+-  `Contributing <https://python-autopypath.readthedocs.io/en/latest/contributing.html>`_
+-  `Code of Conduct <https://python-autopypath.readthedocs.io/en/latest/code_of_conduct.html>`_
+
 What is autopypath?
 -------------------
 
 **autopypath** is a library that simplifies the management of the Python module
-search path (`sys.path`) for testing and development environments.
+search path (``sys.path``) for testing and development environments.
 
-It automatically detects your project root (via `.git`, `pyproject.toml`, etc.)
-and intelligently adds source directories to `sys.path` at runtime.
+It automatically detects your project root (via `.git <https://git-scm.com/>`_,
+`pyproject.toml <https://python-poetry.org/docs/pyproject/>`_, etc.)
+and intelligently adds source directories to ``sys.path`` at runtime.
+
+It *does not* read ``.env`` files to derive
+`PYTHONPATH <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH>`_ because
+the semantics cannot be consistently interpreted across different operating systems.
+
+For example, consider ``PYTHONPATH=src:test;lib``:
+
+* On POSIX, ``PYTHONPATH`` is separated by ``:`` → ``["src", "test;lib"]``
+* On Windows, ``PYTHONPATH`` is separated by ``;`` → ``["src:test", "lib"]``
+* And the intent may have been ``["src", "test", "lib"]``
+
+All of those interpretations are "reasonable", so autopypath avoids guessing
+what was meant and instead uses ``pyproject.toml`` or ``autopypath.toml`` for configuration.
 
 The Problem it Solves
 ~~~~~~~~~~~~~~~~~~~~~
 
 In active development, **builds are often broken.**
-Standard test runners (like `pytest` or `tox`) often refuse to start if they
+Standard test runners (like `pytest <https://docs.pytest.org/en/stable/>`_ or
+`tox <https://tox.wiki/>`_) often refuse to start if they
 cannot import the entire package, or if the package hasn't been re-installed
 into the virtual environment after a structural change.
 
@@ -55,19 +78,10 @@ into the virtual environment after a structural change.
 - Other parts of the test suite are failing due to ongoing refactoring.
 
 It is not a replacement for `virtual environments <https://docs.python.org/3/library/venv.html>`_,
-but a resilience tool. It dynamically fixes "Module Not Found" errors on load, allowing you to
-debug a specific file without needing the entire project ecosystem to be in a perfect,
+but a resilience tool. It mitigates path-related ``ModuleNotFoundError`` errors,
+allowing you to debug a specific file without needing the entire project ecosystem to be in a perfect,
 deployable state.
 
-Documentation
--------------
-
--  `Usage <https://python-autopypath.readthedocs.io/en/latest/usage.html>`_
--  `Configuration <https://python-autopypath.readthedocs.io/en/latest/configuration.html>`_
--  `Public API <https://python-autopypath.readthedocs.io/en/latest/public_api.html>`_
--  `Contributing <https://python-autopypath.readthedocs.io/en/latest/contributing.html>`_
--  `Code of Conduct <https://python-autopypath.readthedocs.io/en/latest/code_of_conduct.html>`_
-
 Installation
 ------------
 
@@ -90,44 +104,47 @@ Installing from Source
 Development Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-For development purposes, you can install `autopypath` in editable mode. To make this easier, a `bootstrap.py` script is provided.
+For development purposes, you can install ``autopypath`` in editable mode.
+To make this easier, a ``bootstrap.py`` script is provided.
 
 .. code-block:: shell
 
    git clone https://github.com/JerilynFranz/python-autopypath.git
    cd python-autopypath
    python3 bootstrap.py
-   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+   source .venv/bin/activate  # On Windows use .venv\Scripts\activate
 
 This script will:
-1.  Set up the development environment (`uv` sync).
-2.  Install `autopypath` in editable mode.
+
+1.  Set up the development environment (``uv sync --all-groups``).
+2.  Install ``autopypath`` in editable mode.
 3.  Install Git hooks for pre-commit checks.
-4.  Install development tools like `tox`, `sphinx`, and `ruff`.
+4.  Install development tools like `tox <https://tox.wiki/>`_, `sphinx <https://www.sphinx-doc.org/en/master/>`_, and `ruff <https://ruff.rs/>`_.
 
 Usage
 -----
 
-Simply import `autopypath` at the top of your test script. It will
-automatically detect the project root and adjust `sys.path` accordingly
-(by default adding `src`, `lib`, `src/tests`, and `tests` directories if they exist).
+Simply import ``autopypath`` at the top of your test script. It will
+automatically detect the project root and adjust ``sys.path`` accordingly
+(by default adding ``src``, ``lib``, ``src/tests``, and ``tests`` directories if they exist).
 
-It does not add '.' to `sys.path` by default to avoid conflicts with subdirectories
+It does not add ``.`` to ``sys.path`` by default to avoid conflicts with subdirectories
 that are NOT intended to be packages, but if you want to include the repo root
-directory, you can configure it via `pyproject.toml` or `autopypath.toml`.
+directory, you can configure it
+via `pyproject.toml <https://python-poetry.org/docs/pyproject/>`_ or ``autopypath.toml``.
 
-Here is an example `tests/my_test_script.py`:
+Here is an example:
 
 .. code-block:: python
 
-   import autopypath  # <--- This line magics the sys.path
+   import autopypath  # <--- This line adjusts the sys.path
    import pytest
 
    # Now these imports work without installing the package
    import mypackage.my_module
 
    if __name__ == '__main__':
-       pytest.main([__file__])
+      pytest.main([__file__])
 
 You can now run this file directly:
 
@@ -138,33 +155,29 @@ You can now run this file directly:
 Configuration
 -------------
 
-autopypath automatically detects `pyproject.toml`. You can configure it
-by adding a ``[tool.autopypath]`` section.
+autopypath automatically detects `pyproject.toml <https://python-poetry.org/docs/pyproject/>`_.
+You can configure it by adding a ``[tool.autopypath]`` section.
 
 **Example `pyproject.toml`:**
 
 .. code-block:: toml
 
-    [tool.autopypath]
-    paths = ["lib", "src/tests", ".", "src"]
+   [tool.autopypath]
+   paths = ["lib", "src/tests", ".", "src"]
 
-If you do not use `pyproject.toml`, you can create an `autopypath.toml` file
-either in your root directory or in subdirectories such as `src` or `tests`
+If you do not use ``pyproject.toml``, you can create an ``autopypath.toml``  file
+either in your root directory or in subdirectories such as ``src`` or ``tests``
 and it will be detected automatically. This can be useful for monorepos or
-multi-package repositories and allows customization of `sys.path` per sub-project
+multi-package repositories and allows customization of ``sys.path`` per sub-project
 or for detection of the project root in non-standard layouts.
 
 **Example `autopypath.toml`:**
 
 .. code-block:: toml
 
-    [tool.autopypath]
-    paths = ["src", "src/lib", "tests"]
-    repo_markers = {".git" = "dir"}
-
+   [tool.autopypath]
+   paths = ["src", "src/lib", "tests"]
+   repo_markers = {".git" = "dir"}
+ 
 This file can be placed in the root of your project or in any directory
 that is a parent of your test scripts (but still inside the repo).
-
-You can use it to customize which directories are added to `sys.path`, or to
-specify custom repository markers for detecting the project root as well
-as other settings affecting path resolution behavior.

README.rst

@@ -135,6 +135,13 @@ To contribute code or documentation updates to `autopypath`, follow these steps:
 
 10. Engage in the code review process and make any necessary changes based on feedback.
 
+
+uv.lock
+-------
+
+uv.lock is included in the source distribution to support reproducible
+builds and independent verification. Use of uv is optional for contributors.
+
 Need Help?
 ----------
 

docs_source/contributing.rst

@@ -52,14 +52,29 @@ What is autopypath?
 **autopypath** is a library that simplifies the management of the Python module
 search path (:data:`sys.path`) for testing and development environments.
 
-It automatically detects your project root (via `.git`, `pyproject.toml`, etc.)
+It automatically detects your project root (via `.git <https://git-scm.com/>`_,
+`pyproject.toml <https://python-poetry.org/docs/pyproject/>`_, etc.)
 and intelligently adds source directories to :data:`sys.path` at runtime.
 
+It *does not* read ``.env`` files to derive
+`PYTHONPATH <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH>`_ because
+the semantics cannot be consistently interpreted across different operating systems.
+
+For example, consider ``PYTHONPATH=src:test;lib``:
+
+* On POSIX, ``PYTHONPATH`` is separated by ``:`` → ``["src", "test;lib"]``
+* On Windows, ``PYTHONPATH`` is separated by ``;`` → ``["src:test", "lib"]``
+* And the intent may have been ``["src", "test", "lib"]``
+
+All of those interpretations are "reasonable", so autopypath avoids guessing
+what was meant and instead uses ``pyproject.toml`` or ``autopypath.toml`` for configuration.
+
 The Problem it Solves
 ~~~~~~~~~~~~~~~~~~~~~
 
 In active development, **builds are often broken.**
-Standard test runners (like `pytest` or `tox`) often refuse to start if they
+Standard test runners (like `pytest <https://docs.pytest.org/en/stable/>`_ or
+`tox <https://tox.wiki/>`_) often refuse to start if they
 cannot import the entire package, or if the package hasn't been re-installed
 into the virtual environment after a structural change.
 
@@ -70,18 +85,10 @@ into the virtual environment after a structural change.
 - Other parts of the test suite are failing due to ongoing refactoring.
 
 It is not a replacement for `virtual environments <https://docs.python.org/3/library/venv.html>`_,
-but a resilience tool. It dynamically fixes "Module Not Found" errors on load, allowing you to
-debug a specific file without needing the entire project ecosystem to be in a perfect,
+but a resilience tool. It mitigates path-related :class:`ModuleNotFoundError` errors,
+allowing you to debug a specific file without needing the entire project ecosystem to be in a perfect,
 deployable state.
 
-Documentation
--------------
-
--  `Usage <https://python-autopypath.readthedocs.io/en/latest/usage.html>`_
--  `Configuration <https://python-autopypath.readthedocs.io/en/latest/configuration.html>`_
--  `Contributing <https://python-autopypath.readthedocs.io/en/latest/contributing.html>`_
--  `Code of Conduct <https://python-autopypath.readthedocs.io/en/latest/code_of_conduct.html>`_
-
 Installation
 ------------
 
@@ -104,45 +111,48 @@ Installing from Source
 Development Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-For development purposes, you can install `autopypath` in editable mode.
-To make this easier, a `bootstrap.py` script is provided.
+For development purposes, you can install ``autopypath`` in editable mode.
+To make this easier, a ``bootstrap.py`` script is provided.
 
 .. code-block:: shell
 
    git clone https://github.com/JerilynFranz/python-autopypath.git
    cd python-autopypath
    python3 bootstrap.py
-   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+   source .venv/bin/activate  # On Windows use .venv\Scripts\activate
 
 This script will:
-1.  Set up the development environment (`uv` sync).
-2.  Install `autopypath` in editable mode.
+
+1.  Set up the development environment (``uv sync --all-groups``).
+2.  Install ``autopypath`` in editable mode.
 3.  Install Git hooks for pre-commit checks.
-4.  Install development tools like `tox`, `sphinx`, and `ruff`.
+4.  Install development tools like `tox <https://tox.wiki/>`_, `sphinx <https://www.sphinx-doc.org/en/master/>`_, and `ruff <https://ruff.rs/>`_.
 
 Usage
 -----
 
-Simply import `autopypath` at the top of your test script. It will
+Simply import ``autopypath`` at the top of your test script. It will
 automatically detect the project root and adjust :data:`sys.path` accordingly
-(by default adding `src`, `lib`, `src/tests`, and `tests` directories if they exist).
+(by default adding ``src``, ``lib``, ``src/tests``, and ``tests`` directories if they exist).
 
-It does not add '.' to :data:`sys.path` by default to avoid conflicts with subdirectories
+It does not add ``.`` to :data:`sys.path` by default to avoid conflicts with subdirectories
 that are NOT intended to be packages, but if you want to include the repo root
-directory, you can configure it via `pyproject.toml` or `autopypath.toml`.
+directory, you can configure it
+via `pyproject.toml <https://python-poetry.org/docs/pyproject/>`_ or ``autopypath.toml``.
 
-Here is an example `tests/my_test_script.py`:
+Here is an example:
 
 .. code-block:: python
+   :caption: tests/my_test_script.py
 
-   import autopypath  # <--- This line magics the sys.path
+   import autopypath  # <--- This line adjusts the sys.path
    import pytest
 
    # Now these imports work without installing the package
    import mypackage.my_module
 
    if __name__ == '__main__':
-       pytest.main([__file__])
+      pytest.main([__file__])
 
 You can now run this file directly:
 
@@ -153,29 +163,31 @@ You can now run this file directly:
 Configuration
 -------------
 
-autopypath automatically detects `pyproject.toml`. You can configure it by
-adding a ``[tool.autopypath]`` section.
+autopypath automatically detects `pyproject.toml <https://python-poetry.org/docs/pyproject/>`_.
+You can configure it by adding a ``[tool.autopypath]`` section.
 
 **Example `pyproject.toml`:**
 
 .. code-block:: toml
+   :caption: pyproject.toml
 
-    [tool.autopypath]
-    paths = ["lib", "src/tests", ".", "src"]
+   [tool.autopypath]
+   paths = ["lib", "src/tests", ".", "src"]
 
-If you do not use `pyproject.toml`, you can create an `autopypath.toml` file
-either in your root directory or in subdirectories such as `src` or `tests`
+If you do not use ``pyproject.toml``, you can create an ``autopypath.toml``  file
+either in your root directory or in subdirectories such as ``src`` or ``tests``
 and it will be detected automatically. This can be useful for monorepos or
 multi-package repositories and allows customization of :data:`sys.path` per sub-project
 or for detection of the project root in non-standard layouts.
 
 **Example `autopypath.toml`:**
 
 .. code-block:: toml
+   :caption: autopypath.toml
 
-    [tool.autopypath]
-    paths = ["src", "src/lib", "tests"]
-    repo_markers = {".git" = "dir"}
-
+   [tool.autopypath]
+   paths = ["src", "src/lib", "tests"]
+   repo_markers = {".git" = "dir"}
+ 
 This file can be placed in the root of your project or in any directory
 that is a parent of your test scripts (but still inside the repo).

docs_source/index.rst

@@ -243,6 +243,8 @@ exclude = [
 exclude = [
     ".trunk/",
     ".git/",
+    ".vscode/",
+    "python-autopypath.code-workspace",
     "coverage/",
     "coverage_html_report/",
     "examples/",