# xsdata-rootfinder
A Python package designed to analyze Python source files and identify root models. This package supports different model types, including dataclass, Pydantic, and attrs, making it easy to work with various schema formats.
## Features
- **Single File Analysis:** Identify root models from a single Python source file.
- **Batch Processing:** Analyze multiple files or directories with support for recursion.
- **Model Types:** Supports dataclasses, Pydantic models, and attrs classes.
- **Multiprocessing:** Optional multiprocessing for faster batch analysis.
## Installation
To install `xsdata-rootfinder`, run the following command:
```bash
pip install xsdata-rootfinder
```
## How It Works
The `xsdata-rootfinder` package analyzes Python source files to identify root models. A root model is defined as a class that is present in a file but not referenced within it. This is specifically desinged for models generated by `xsdata` but theoretically could be used for any models.
Any number of files or paths can be passed as arguments to the `root_finders` function. One caveat is that all files passed must reflect the layout of the codebase they exist in. This is important so as to accurately match any local import to the correct python file.
### Drawbacks
There are two edge cases that are not taken into account within the logic. Thus, there could be inaccurate results. These issues will be patched up in the next release.
1. Importing from a `PYTHONPATH` Module
- Any file that imports models from a directory that is included in the `PYTHONPATH` variable.
2. Import Forwarding Models
- Any file that imports models from files that are import forwarding (i.e. not importing them from where they are defined).
### Functionality Overview
#### `root_finder`
Analyze a single Python source file to find root models.
```python
def root_finder(source: CodeOrStrOrPath, xsd_models: XsdModels = "dataclass") -> Optional[List[RootModel]]:
...
```
- **Arguments:**
- `source`: Python source to analyze (code string, file path, or path-like object).
- `xsd_models`: Specifies model type (`'dataclass'`, `'pydantic'`, or `'attrs'`).
- **Returns:** List of root models or `None`.
#### Example Usage
```python
from xsdata_rootfinder import root_finder
roots = root_finder("path/to/source.py", xsd_models="pydantic")
```
#### `root_finders`
Analyze a single directory or multiple files/directories to find root models. If a collection is passed, then each item in that collection must be a string or Path object representing an existing file or directory.
```python
def root_finders(
sources: Union[StrOrPath, Collection[StrOrPath]],
xsd_models: XsdModels = "dataclass",
directory_walk: bool = False,
ignore_init_files: bool = True,
multiprocessing: Optional[MultiprocessingSettings] = None,
) -> Optional[List[RootModel]]:
...
```
- **Arguments:**
- `sources`: One or more paths to analyze.
- `xsd_models`: Specifies model type (`'dataclass'`, `'pydantic'`, or `'attrs'`).
- `directory_walk`: Boolean indicating a recursive search of directories.
- `ignore_init_files`: Boolean indicating whether to ignore `__init__.py` files.
- `multiprocessing`: Settings for parallel file processing.
- **Returns:** List of root models or `None`.
#### Example Usage
```python
from xsdata_rootfinder import root_finders
roots = root_finders(
["path/to/source1.py", "path/to/source2.py"],
xsd_models="attrs",
directory_walk=True,
multiprocessing=None
)
```
## License
This project is licensed under the terms of the MIT License.
## Workflow Details
GitHub Actions automate CI/CD workflows, including tests and package deployment.
Raw data
{
"_id": null,
"home_page": "https://github.com/galactixx/xsdata-rootfinder",
"name": "xsdata-rootfinder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "xsdata, root, schema, top-level",
"author": "galactixx",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8e/31/dad1cd3f3ef6b5c7a78c7218efa759936bad6992b0d59583b7dfd7a9d7bc/xsdata_rootfinder-0.1.0.tar.gz",
"platform": null,
"description": "# xsdata-rootfinder\n\nA Python package designed to analyze Python source files and identify root models. This package supports different model types, including dataclass, Pydantic, and attrs, making it easy to work with various schema formats.\n\n## Features\n- **Single File Analysis:** Identify root models from a single Python source file.\n- **Batch Processing:** Analyze multiple files or directories with support for recursion.\n- **Model Types:** Supports dataclasses, Pydantic models, and attrs classes.\n- **Multiprocessing:** Optional multiprocessing for faster batch analysis.\n\n## Installation\nTo install `xsdata-rootfinder`, run the following command:\n\n```bash\npip install xsdata-rootfinder\n```\n\n## How It Works\nThe `xsdata-rootfinder` package analyzes Python source files to identify root models. A root model is defined as a class that is present in a file but not referenced within it. This is specifically desinged for models generated by `xsdata` but theoretically could be used for any models.\n\nAny number of files or paths can be passed as arguments to the `root_finders` function. One caveat is that all files passed must reflect the layout of the codebase they exist in. This is important so as to accurately match any local import to the correct python file.\n\n### Drawbacks\nThere are two edge cases that are not taken into account within the logic. Thus, there could be inaccurate results. These issues will be patched up in the next release.\n\n1. Importing from a `PYTHONPATH` Module\n - Any file that imports models from a directory that is included in the `PYTHONPATH` variable.\n2. Import Forwarding Models\n - Any file that imports models from files that are import forwarding (i.e. not importing them from where they are defined).\n\n### Functionality Overview\n#### `root_finder`\nAnalyze a single Python source file to find root models.\n\n```python\ndef root_finder(source: CodeOrStrOrPath, xsd_models: XsdModels = \"dataclass\") -> Optional[List[RootModel]]:\n ...\n```\n\n- **Arguments:**\n - `source`: Python source to analyze (code string, file path, or path-like object).\n - `xsd_models`: Specifies model type (`'dataclass'`, `'pydantic'`, or `'attrs'`).\n- **Returns:** List of root models or `None`.\n\n#### Example Usage\n```python\nfrom xsdata_rootfinder import root_finder\n\nroots = root_finder(\"path/to/source.py\", xsd_models=\"pydantic\")\n```\n\n#### `root_finders`\nAnalyze a single directory or multiple files/directories to find root models. If a collection is passed, then each item in that collection must be a string or Path object representing an existing file or directory.\n\n```python\ndef root_finders(\n sources: Union[StrOrPath, Collection[StrOrPath]],\n xsd_models: XsdModels = \"dataclass\",\n directory_walk: bool = False,\n ignore_init_files: bool = True,\n multiprocessing: Optional[MultiprocessingSettings] = None,\n) -> Optional[List[RootModel]]:\n ...\n```\n\n- **Arguments:**\n - `sources`: One or more paths to analyze.\n - `xsd_models`: Specifies model type (`'dataclass'`, `'pydantic'`, or `'attrs'`).\n - `directory_walk`: Boolean indicating a recursive search of directories.\n - `ignore_init_files`: Boolean indicating whether to ignore `__init__.py` files.\n - `multiprocessing`: Settings for parallel file processing.\n- **Returns:** List of root models or `None`.\n\n#### Example Usage\n```python\nfrom xsdata_rootfinder import root_finders\n\nroots = root_finders(\n [\"path/to/source1.py\", \"path/to/source2.py\"],\n xsd_models=\"attrs\",\n directory_walk=True,\n multiprocessing=None\n)\n```\n\n## License\nThis project is licensed under the terms of the MIT License.\n\n## Workflow Details\nGitHub Actions automate CI/CD workflows, including tests and package deployment.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python package to identify the top-level dataclass in files generated by xsdata, representing the root schema element.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/galactixx/xsdata-rootfinder",
"Repository": "https://github.com/galactixx/xsdata-rootfinder"
},
"split_keywords": [
"xsdata",
" root",
" schema",
" top-level"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fef225d5ece82aac96af66f5e9ad1350d2642f06648b77f2388bc24abcb485e2",
"md5": "68f793e3301436b1427232e66c5be1cd",
"sha256": "ef7d75f0b45cdb8ad3dd695e529c5a467a0ad37518cacd380fc3ed68ec903cf6"
},
"downloads": -1,
"filename": "xsdata_rootfinder-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68f793e3301436b1427232e66c5be1cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13285,
"upload_time": "2025-02-07T03:19:08",
"upload_time_iso_8601": "2025-02-07T03:19:08.041059Z",
"url": "https://files.pythonhosted.org/packages/fe/f2/25d5ece82aac96af66f5e9ad1350d2642f06648b77f2388bc24abcb485e2/xsdata_rootfinder-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e31dad1cd3f3ef6b5c7a78c7218efa759936bad6992b0d59583b7dfd7a9d7bc",
"md5": "e9258c37645789d90dc14adf718ba97d",
"sha256": "95cf4be1a6afa0461f0a265c58bbd7cb419919c8d6b696b42ef9004e9f5dd807"
},
"downloads": -1,
"filename": "xsdata_rootfinder-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e9258c37645789d90dc14adf718ba97d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13605,
"upload_time": "2025-02-07T03:19:10",
"upload_time_iso_8601": "2025-02-07T03:19:10.029523Z",
"url": "https://files.pythonhosted.org/packages/8e/31/dad1cd3f3ef6b5c7a78c7218efa759936bad6992b0d59583b7dfd7a9d7bc/xsdata_rootfinder-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-07 03:19:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "galactixx",
"github_project": "xsdata-rootfinder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "libcst",
"specs": [
[
">=",
"1.00"
]
]
},
{
"name": "pathvalidate",
"specs": [
[
">=",
"3.2.0"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
">=",
"4.6.0"
]
]
}
],
"tox": true,
"lcname": "xsdata-rootfinder"
}
JSON
