astlab 0.1.0__tar.gz

astlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danil Troshnev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

astlab-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: astlab
+Version: 0.1.0
+Summary: provides an intuitive API for building and manipulating Abstract Syntax Trees (ASTs) to generate Python code.
+License: MIT
+Keywords: python,codegen
+Author: zerlok
+Author-email: danil.troshnev@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/zerlok/astlab
+Project-URL: Issues, https://github.com/zerlok/astlab/issues
+Description-Content-Type: text/markdown
+
+# astlab
+
+[![Latest Version](https://img.shields.io/pypi/v/astlab.svg)](https://pypi.python.org/pypi/astlab)
+[![Python Supported Versions](https://img.shields.io/pypi/pyversions/astlab.svg)](https://pypi.python.org/pypi/astlab)
+[![MyPy Strict](https://img.shields.io/badge/mypy-strict-blue)](https://mypy.readthedocs.io/en/stable/getting_started.html#strict-mode-and-configuration)
+[![Test Coverage](https://codecov.io/gh/zerlok/astlab/branch/main/graph/badge.svg)](https://codecov.io/gh/zerlok/astlab)
+[![Downloads](https://img.shields.io/pypi/dm/astlab.svg)](https://pypistats.org/packages/astlab)
+[![GitHub stars](https://img.shields.io/github/stars/zerlok/astlab)](https://github.com/zerlok/astlab/stargazers)
+
+**astlab** is a Python library that provides an intuitive API for building and manipulating Abstract Syntax Trees (ASTs) to generate Python code. With **astlab**, you can easily create Python modules, classes, fields, and more using a simple and readable syntax, and convert the AST back into executable Python code.
+
+## Features
+
+- **Easy AST construction**: Build Python code using a fluent and intuitive API.
+- **Code generation**: Convert your AST into valid Python code, forget about jinja templates.
+- **Supports nested scopes & auto imports**: Create nested classes, methods, and fields effortlessly. Reference types from other modules easily.
+- **Highly customizable**: Extend and modify the API to suit your needs.
+
+## Installation
+
+You can install **astlab** from PyPI using `pip`:
+
+```bash
+pip install astlab
+```
+
+## Usage
+
+### Simple example
+
+Here's a basic example of how to use **astlab** to create a Python module with a dataclass.
+
+```python
+import astlab
+
+# Create a new Python module
+with astlab.module("foo") as foo:
+    # Build a "Bar" dataclass
+    with foo.class_def("Bar").dataclass() as bar:
+        # Define a field "spam" of type int
+        bar.field_def("spam", int)
+
+# Generate and print the Python code from the AST
+print(foo.render())
+```
+
+### Output:
+
+```python
+import builtins
+import dataclasses
+
+@dataclasses.dataclass()
+class Bar:
+    spam: builtins.int
+```
+

astlab-0.1.0/README.md

@@ -0,0 +1,56 @@
+# astlab
+
+[![Latest Version](https://img.shields.io/pypi/v/astlab.svg)](https://pypi.python.org/pypi/astlab)
+[![Python Supported Versions](https://img.shields.io/pypi/pyversions/astlab.svg)](https://pypi.python.org/pypi/astlab)
+[![MyPy Strict](https://img.shields.io/badge/mypy-strict-blue)](https://mypy.readthedocs.io/en/stable/getting_started.html#strict-mode-and-configuration)
+[![Test Coverage](https://codecov.io/gh/zerlok/astlab/branch/main/graph/badge.svg)](https://codecov.io/gh/zerlok/astlab)
+[![Downloads](https://img.shields.io/pypi/dm/astlab.svg)](https://pypistats.org/packages/astlab)
+[![GitHub stars](https://img.shields.io/github/stars/zerlok/astlab)](https://github.com/zerlok/astlab/stargazers)
+
+**astlab** is a Python library that provides an intuitive API for building and manipulating Abstract Syntax Trees (ASTs) to generate Python code. With **astlab**, you can easily create Python modules, classes, fields, and more using a simple and readable syntax, and convert the AST back into executable Python code.
+
+## Features
+
+- **Easy AST construction**: Build Python code using a fluent and intuitive API.
+- **Code generation**: Convert your AST into valid Python code, forget about jinja templates.
+- **Supports nested scopes & auto imports**: Create nested classes, methods, and fields effortlessly. Reference types from other modules easily.
+- **Highly customizable**: Extend and modify the API to suit your needs.
+
+## Installation
+
+You can install **astlab** from PyPI using `pip`:
+
+```bash
+pip install astlab
+```
+
+## Usage
+
+### Simple example
+
+Here's a basic example of how to use **astlab** to create a Python module with a dataclass.
+
+```python
+import astlab
+
+# Create a new Python module
+with astlab.module("foo") as foo:
+    # Build a "Bar" dataclass
+    with foo.class_def("Bar").dataclass() as bar:
+        # Define a field "spam" of type int
+        bar.field_def("spam", int)
+
+# Generate and print the Python code from the AST
+print(foo.render())
+```
+
+### Output:
+
+```python
+import builtins
+import dataclasses
+
+@dataclasses.dataclass()
+class Bar:
+    spam: builtins.int
+```

astlab-0.1.0/pyproject.toml

@@ -0,0 +1,135 @@
+[tool.poetry]
+name = "astlab"
+version = "0.1.0"
+description = "provides an intuitive API for building and manipulating Abstract Syntax Trees (ASTs) to generate Python code."
+authors = ["zerlok <danil.troshnev@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "python",
+    "codegen",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/zerlok/astlab"
+Issues = "https://github.com/zerlok/astlab/issues"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.13.0"
+pytest = "^8.3.3"
+pytest-cov = "^6.0.0"
+pytest-mypy-plugins = "^3.1.2"
+ruff = ">=0.7.4,<0.9.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.ruff]
+target-version = "py39"
+include = ["src/**/*.py", "tests/**/*.py"]
+force-exclude = true
+line-length = 120
+output-format = "pylint"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN", # because we use mypy
+    "D", # TODO: add docstrings to public code
+    "FA", # TODO: consider should we use __annotations__
+    "TD", # no task tracking
+    "FIX", # TODO: consider enable it against new code on pull requests
+    "COM812", # because ruff format suggests to skip it
+    "ISC001", # because ruff format suggests to skip it
+    "RET505", # clashes with mypy exhaustiveness check
+    "S101", # allow asserts for tests checks and mypy help
+    # TODO: stop ignore this rule
+    "UP007", # because of 3.9 support
+    # TODO: stop ignore this rule
+    "SIM117", # because ast builder 2.0 uses with statement to build contextual scope statemetns
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "PLR0913", # test functions can use a lots of arguments and fixtures
+]
+
+
+[tool.mypy]
+files = ["src", "tests"]
+strict = true
+disallow_any_unimported = true
+disallow_any_expr = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_return_any = true
+warn_unreachable = true
+strict_equality = true
+strict_optional = true
+enable_error_code = [
+    "redundant-self",
+    "redundant-expr",
+    "possibly-undefined",
+    "truthy-bool",
+    "truthy-iterable",
+    "ignore-without-code",
+    "unused-awaitable",
+    "explicit-override",
+    "mutable-override",
+    "unimported-reveal",
+    "narrowed-type-not-subtype",
+]
+
+# NOTE: allow return `typing.Any` in test fixtures (e.g. mock objects created with `create_autospec`)
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_any_expr = false
+disallow_any_explicit = false
+warn_return_any = false
+
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+]
+addopts = [
+    "--cov=src",
+    "--cov-report=term-missing",
+]
+testpaths = [
+    "tests",
+]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "@abc.abstractmethod",
+    "if __name__ == .__main__.:",
+    "if t.TYPE_CHECKING:",
+]
+show_missing = true

astlab-0.1.0/src/astlab/__init__.py

@@ -0,0 +1,6 @@
+__all__ = [
+    "module",
+    "package",
+]
+
+from astlab.builder import module, package

astlab-0.1.0/src/astlab/_typing.py

@@ -0,0 +1,22 @@
+__all__ = [
+    "Self",
+    "TypeGuard",
+    "assert_never",
+    "override",
+]
+
+import typing as t
+
+# NOTE: this allows to use methods with `Self` during runtime (when typing_extensions is not installed).
+if t.TYPE_CHECKING:
+    from typing_extensions import Self, TypeGuard, assert_never, override
+
+else:
+    Self = t.Any
+    TypeGuard = t.Optional
+
+    def assert_never(*args: object, **kwargs: object) -> t.NoReturn:
+        raise RuntimeError(args, kwargs)  # pragma: no cover
+
+    def override(func: object) -> object:
+        return func

astlab-0.1.0/src/astlab/abc.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+__all__ = [
+    "ExpressionASTBuilder",
+    "StatementASTBuilder",
+    "TypeInfoProvider",
+]
+
+
+import abc
+import typing as t
+
+if t.TYPE_CHECKING:
+    import ast
+
+    from astlab.info import TypeInfo
+
+
+class ExpressionASTBuilder(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def build(self) -> ast.expr:
+        raise NotImplementedError
+
+
+class StatementASTBuilder(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def build(self) -> t.Sequence[ast.stmt]:
+        raise NotImplementedError
+
+
+class TypeInfoProvider(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def provide_type_info(self) -> TypeInfo:
+        raise NotImplementedError