{"id":7720,"library":"single-source","title":"Python Single-Source Versioning Library","description":"The `single-source` library provides a unified way to access a Python project's version directly from code, aligning with PEP 621-style projects. It aims to establish a single source of truth for version information, preventing inconsistencies that arise from manual updates across multiple files. The library supports Python 3.8 and newer versions and is actively maintained.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/rabbit72/single-source.git","tags":["versioning","metadata","packaging","pep621","build-system"],"install":[{"cmd":"pip install single-source","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.8 or newer for compatibility.","package":"python","optional":false}],"imports":[{"symbol":"get_version","correct":"from single_source import get_version"},{"symbol":"VersionNotFoundError","correct":"from single_source import VersionNotFoundError"}],"quickstart":{"code":"from pathlib import Path\nfrom single_source import get_version, VersionNotFoundError\n\n# For demonstration, assume a pyproject.toml exists in the parent directory.\n# In a real project, this path would point to your project root.\ntry:\n    # Adjust path_to_pyproject_dir to point to your project's root.\n    # For an executable script, .parent.parent might work if pyproject.toml is two levels up.\n    # For a library in a package, it might be Path(__file__).parent.parent.parent\n    project_root = Path(__file__).resolve().parent\n    # In a typical project, if your script is in `src/my_package/my_module.py` and pyproject.toml is at project root:\n    # project_root = Path(__file__).resolve().parents[3] # Adjust as needed\n    \n    # Example of a simplified path for a quick demonstration setup:\n    # Create a dummy pyproject.toml for this example to be runnable\n    dummy_project_dir = Path('./dummy_project_for_single_source_test')\n    dummy_project_dir.mkdir(exist_ok=True)\n    pyproject_content = '[project]\\nname = \"my_test_package\"\\nversion = \"1.2.3\"\\n'\n    (dummy_project_dir / 'pyproject.toml').write_text(pyproject_content)\n\n    # Now get the version from the dummy project\n    version = get_version(dummy_project_dir)\n    print(f\"Project version (from dummy_project): {version}\")\n\n    # Example with explicit error raising\n    # Clean up dummy project\n    (dummy_project_dir / 'pyproject.toml').unlink()\n    dummy_project_dir.rmdir()\n\n    # Attempt to get version from a non-existent path to demonstrate VersionNotFoundError\n    non_existent_path = Path('./non_existent_project')\n    print(f\"\\nAttempting to get version from non-existent path '{non_existent_path}' with error raising...\")\n    try:\n        get_version(non_existent_path, raise_exc=True)\n    except VersionNotFoundError as e:\n        print(f\"Caught expected error: {e}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Ensure cleanup even if errors occur before the explicit unlink/rmdir\n    dummy_project_dir = Path('./dummy_project_for_single_source_test')\n    if dummy_project_dir.exists():\n        if (dummy_project_dir / 'pyproject.toml').exists():\n            (dummy_project_dir / 'pyproject.toml').unlink()\n        if dummy_project_dir.is_dir():\n            dummy_project_dir.rmdir()","lang":"python","description":"This quickstart demonstrates how to retrieve the project version using `get_version`. It shows how to pass the path to your project's root directory (where `pyproject.toml` resides) and how to handle the `VersionNotFoundError` if the version cannot be found when `raise_exc=True` is specified. For a runnable example, a dummy `pyproject.toml` is created and cleaned up."},"warnings":[{"fix":"To explicitly raise a `VersionNotFoundError` when the version is not found, call `get_version(..., raise_exc=True)`. Implement proper error handling for `VersionNotFoundError` to manage cases where version retrieval fails.","message":"By default, `get_version()` returns an empty string (`\"\"`) if it cannot locate the project version from `pyproject.toml`, `setup.py`, or `__init__.py`. This can lead to silent failures if an empty string is not an expected valid version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully construct the `pathlib.Path` object to correctly represent your project's root directory. For a package installed via `pip`, `importlib.metadata.version('your-package-name')` might be a more robust runtime solution, as `single-source` is primarily for development-time versioning.","message":"The `path_to_pyproject_dir` argument for `get_version()` must accurately point to the directory containing your project's version source (e.g., `pyproject.toml`). An incorrect path will cause the library to fail in finding the version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project's environment uses Python 3.8 or a later version. Upgrade your Python interpreter if necessary.","message":"The `single-source` library explicitly requires Python 3.8 or newer. Attempting to use it with older Python versions (e.g., Python 2.x or Python 3.7 and below) will result in `SyntaxError` or `ModuleNotFoundError` due to incompatible language features and module structures.","severity":"breaking","affected_versions":"Python <3.8"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that `pyproject.toml` exists in the `path_to_pyproject_dir` you provided to `get_version()`. Ensure the `[project].version` key is correctly defined in `pyproject.toml`, or if using a dynamic version, that your build system is configured to generate it.","cause":"The `get_version()` function was called with `raise_exc=True`, but it could not find the project version in the expected `pyproject.toml` file (or other configured source) at the specified path.","error":"single_source.VersionNotFoundError: Version not found in pyproject.toml"},{"fix":"Install the library using `pip install single-source`. If using a virtual environment, ensure it is activated before installation.","cause":"The `single-source` library is not installed in the current Python environment, or the Python interpreter cannot find it in its `sys.path`.","error":"ModuleNotFoundError: No module named 'single_source'"},{"fix":"Provide the necessary `pathlib.Path` argument to `get_version()`. For example: `get_version(Path(__file__).parent.parent)` to look two directories up from the current script.","cause":"The `get_version` function requires at least one argument, a `pathlib.Path` object pointing to the root directory of your project where the version information is located.","error":"TypeError: get_version() missing 1 required positional argument: 'path_to_pyproject_dir'"}]}