# aimport
A minimal library for python: Adding support for smart imports with automatic path resolution.
## Usage
```python
import aimport
```
This automatically adds relevant directories to `sys.path` based on `__aimport__` anchor files found in the directory tree.
## Features
- **Smart path resolution**: Automatically discovers project roots using `__aimport__` anchor files
- **Anchor file content support**: `__aimport__` files can contain paths that will be used instead of the file location
- **Multiple paths support**: **NEW in v2.1.0**: `__aimport__` files can contain multiple paths, one per line
- **Fallback support**: Falls back to `__init__.py` files when no `__aimport__` files are found
- **Priority ordering**: **BREAKING CHANGE v2.0.0**: New paths are now prepended to `sys.path` instead of appended, giving them higher import priority
- **Duplicate prevention**: Avoids adding duplicate paths to `sys.path`
- **Automatic execution**: Works immediately upon import
## Breaking Changes in v2.0.0
⚠️ **Import Priority Change**: Starting with v2.0.0, discovered paths are prepended to `sys.path` instead of appended. This means modules in aimport-discovered directories will take precedence over existing `sys.path` entries. This change ensures that project-local modules are found before system or virtual environment modules.
## New Features in v2.1.0
🎉 **Multiple Paths Support**: `__aimport__` files can now contain multiple paths, one per line. This allows a single anchor file to reference multiple directories that should be added to the import path.
## How It Works
1. **Anchor File Discovery**: Searches upward from the starting directory for `__aimport__` files
2. **Content Processing**: If an `__aimport__` file contains valid paths (one per line), those paths are used; otherwise the file's directory is used
3. **Multiple Path Support**: Each line in an `__aimport__` file is treated as a separate path - empty lines and whitespace-only lines are ignored
4. **Fallback Mechanism**: If no `__aimport__` files are found, falls back to searching for `__init__.py` files
5. **Path Priority**: All discovered paths are added to the beginning of `sys.path` for higher import priority
### Anchor File Format
`__aimport__` files can contain:
- **Empty file**: Uses the directory containing the file
- **Single path**: Uses that path (absolute or relative)
- **Multiple paths**: One path per line, uses all valid paths
Example `__aimport__` file with multiple paths:
```
../lib
./vendor
/absolute/path/to/modules
```
## Testing
The project includes comprehensive unit tests using pytest:
```bash
# Install development dependencies
uv sync --dev
# Run all tests
./test.sh
# Or run pytest directly
uv run pytest tests/ -v
```
### Test Coverage
- 23 comprehensive test cases
- Full coverage of all functions and edge cases
- Integration tests for complex directory structures
- Behavior-focused testing (not implementation details)
## Development
```bash
# Build distribution
python setup.py sdist
# Upload to PyPI
twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "aimport",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "import, path, module, python, sys.path",
"author": "aimport contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/91/45/813e977d996163db52775d15cb370aec8bc1ea0a3eb33f3967b5aeb4ccf3/aimport-2.1.0.tar.gz",
"platform": null,
"description": "# aimport\n\nA minimal library for python: Adding support for smart imports with automatic path resolution.\n\n## Usage\n\n```python\nimport aimport\n```\n\nThis automatically adds relevant directories to `sys.path` based on `__aimport__` anchor files found in the directory tree.\n\n## Features\n\n- **Smart path resolution**: Automatically discovers project roots using `__aimport__` anchor files\n- **Anchor file content support**: `__aimport__` files can contain paths that will be used instead of the file location\n- **Multiple paths support**: **NEW in v2.1.0**: `__aimport__` files can contain multiple paths, one per line\n- **Fallback support**: Falls back to `__init__.py` files when no `__aimport__` files are found\n- **Priority ordering**: **BREAKING CHANGE v2.0.0**: New paths are now prepended to `sys.path` instead of appended, giving them higher import priority\n- **Duplicate prevention**: Avoids adding duplicate paths to `sys.path`\n- **Automatic execution**: Works immediately upon import\n\n## Breaking Changes in v2.0.0\n\n\u26a0\ufe0f **Import Priority Change**: Starting with v2.0.0, discovered paths are prepended to `sys.path` instead of appended. This means modules in aimport-discovered directories will take precedence over existing `sys.path` entries. This change ensures that project-local modules are found before system or virtual environment modules.\n\n## New Features in v2.1.0\n\n\ud83c\udf89 **Multiple Paths Support**: `__aimport__` files can now contain multiple paths, one per line. This allows a single anchor file to reference multiple directories that should be added to the import path.\n\n## How It Works\n\n1. **Anchor File Discovery**: Searches upward from the starting directory for `__aimport__` files\n2. **Content Processing**: If an `__aimport__` file contains valid paths (one per line), those paths are used; otherwise the file's directory is used\n3. **Multiple Path Support**: Each line in an `__aimport__` file is treated as a separate path - empty lines and whitespace-only lines are ignored\n4. **Fallback Mechanism**: If no `__aimport__` files are found, falls back to searching for `__init__.py` files\n5. **Path Priority**: All discovered paths are added to the beginning of `sys.path` for higher import priority\n\n### Anchor File Format\n\n`__aimport__` files can contain:\n- **Empty file**: Uses the directory containing the file\n- **Single path**: Uses that path (absolute or relative)\n- **Multiple paths**: One path per line, uses all valid paths\n\nExample `__aimport__` file with multiple paths:\n```\n../lib\n./vendor\n/absolute/path/to/modules\n```\n\n## Testing\n\nThe project includes comprehensive unit tests using pytest:\n\n```bash\n# Install development dependencies\nuv sync --dev\n\n# Run all tests\n./test.sh\n\n# Or run pytest directly\nuv run pytest tests/ -v\n```\n\n### Test Coverage\n\n- 23 comprehensive test cases\n- Full coverage of all functions and edge cases\n- Integration tests for complex directory structures\n- Behavior-focused testing (not implementation details)\n\n## Development\n\n```bash\n# Build distribution\npython setup.py sdist\n\n# Upload to PyPI\ntwine upload dist/*\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A minimal library for smart Python imports with automatic path resolution",
"version": "2.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/ralf12358/aimport/issues",
"Homepage": "https://github.com/ralf12358/aimport",
"Repository": "https://github.com/ralf12358/aimport"
},
"split_keywords": [
"import",
" path",
" module",
" python",
" sys.path"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb7e1ad43683dff19c8c42e1fa8eacef2afcf21e27bdd0c450651326ef4fbdc5",
"md5": "07e69e882bc067771ff51d7a9ddb0a19",
"sha256": "38ceb283bb2ced984a02ff428863e293416c03dea3429c08318d91e5c48bc6d2"
},
"downloads": -1,
"filename": "aimport-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07e69e882bc067771ff51d7a9ddb0a19",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4569,
"upload_time": "2025-08-14T16:43:21",
"upload_time_iso_8601": "2025-08-14T16:43:21.903165Z",
"url": "https://files.pythonhosted.org/packages/cb/7e/1ad43683dff19c8c42e1fa8eacef2afcf21e27bdd0c450651326ef4fbdc5/aimport-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9145813e977d996163db52775d15cb370aec8bc1ea0a3eb33f3967b5aeb4ccf3",
"md5": "f27af141841e01a3503729447649a660",
"sha256": "a5f533c8c5d2be63422eba14ce34464d29da04dbd12577832755ed53b5b652c2"
},
"downloads": -1,
"filename": "aimport-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f27af141841e01a3503729447649a660",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8830,
"upload_time": "2025-08-14T16:43:23",
"upload_time_iso_8601": "2025-08-14T16:43:23.419877Z",
"url": "https://files.pythonhosted.org/packages/91/45/813e977d996163db52775d15cb370aec8bc1ea0a3eb33f3967b5aeb4ccf3/aimport-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 16:43:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ralf12358",
"github_project": "aimport",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aimport"
}
JSON
