verysimpletree 1.2__tar.gz → 2.0.0__tar.gz

verysimpletree-2.0.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: verysimpletree
+Version: 2.0.0
+Summary: lightweight tree data structure
+Author: Alex Gorji
+Author-email: Alex Gorji <aligorji@hotmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Project-URL: Homepage, https://gitlab.com/alexgorji/verysimpletree.git
+Project-URL: Repository, https://gitlab.com/alexgorji/verysimpletree.git
+Description-Content-Type: text/markdown
+
+An abstract lightweight tree class for managing tree structures.
+
+Requires Python 3.11 or newer.
+
+## Development
+
+Use a current uv release; development and package builds are verified with
+uv 0.13.1. Older uv releases may fail to extract archives used by the current
+build backend.
+
+```sh
+uv sync --locked
+uv run pytest
+uv run mypy verysimpletree --strict
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## GitLab CI and releases
+
+The root `.gitlab-ci.yml` runs lint and strict type checks, tests Python
+3.11-3.14, and builds a wheel and source distribution. Merge requests, branch
+pushes, and tags run validation; duplicate branch pipelines are skipped for
+pushes with an open merge request. Jobs explicitly select their Python
+interpreter rather than relying on the development `.python-version` pin.
+JUnit test reports and built distributions are retained as job artifacts.
+
+To enable publishing on GitLab:
+
+1. Use a runner that supports the configured Python Docker images.
+2. Protect release tags matching `v*` and restrict who can create them.
+3. Add `UV_PUBLISH_TOKEN` as a masked, protected CI/CD variable containing a
+   PyPI API token scoped to the `verysimpletree` project.
+4. Set the version in `pyproject.toml`, update `uv.lock`, and commit the changes.
+5. Push a matching stable version tag, such as `v2.0.0`.
+
+Publishing runs automatically only for protected stable version tags, after
+checks, tests, and the build pass. The tag must match the package version.
+The publish job uploads the build job's artifacts without rebuilding them.
+Branch and merge request pipelines never publish.
+
+## Structural mutations
+
+- `parent.add_child(child)` appends a detached child and returns it.
+- `parent.insert_child(index, child)` inserts a detached child and returns it.
+  Indices follow `list.insert()`: negative indices count from the end, and
+  out-of-range indices are clamped.
+- `parent.remove(child)` detaches a direct child.
+- `parent.replace_child(old, new, index=0)` replaces a direct child in place.
+  `old` can also be a predicate; `index` selects among matching children.
+  Replacing a child with itself is a no-op. The method returns `None`.
+
+Children must have no parent before attachment. Self-insertion, ancestor
+insertion, and attaching an already-parented child raise `ValueError`.
+Subclass child-type checks still apply. Invalid attachments leave the tree
+unchanged. To move a child, remove it from its old parent first:
+
+```python
+old_parent.remove(child)
+new_parent.add_child(child)
+```
+
+Mutation methods update parent pointers, leaf status, and affected traversal,
+leaf, and ancestor-path caches.
+
+## Subclass contract
+
+Implement `_check_child_to_be_added()` to validate allowed child types, raising
+an exception for invalid children without mutating the tree. Structural checks
+are shared by `add_child()`, `insert_child()`, and `replace_child()` through
+`_validate_child_attachment()`.
+
+Inherited structural operations use `_children` as their authoritative child
+storage. Overriding `get_children()` alone does not provide alternative-storage
+support. Subclasses using `_children` should reuse the mutation methods rather
+than assign parent pointers or edit child lists directly.
+
+`get_children()` still returns the mutable backing list for compatibility.
+Direct edits bypass validation and cache invalidation.

verysimpletree-2.0.0/README.md

@@ -0,0 +1,80 @@
+An abstract lightweight tree class for managing tree structures.
+
+Requires Python 3.11 or newer.
+
+## Development
+
+Use a current uv release; development and package builds are verified with
+uv 0.13.1. Older uv releases may fail to extract archives used by the current
+build backend.
+
+```sh
+uv sync --locked
+uv run pytest
+uv run mypy verysimpletree --strict
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## GitLab CI and releases
+
+The root `.gitlab-ci.yml` runs lint and strict type checks, tests Python
+3.11-3.14, and builds a wheel and source distribution. Merge requests, branch
+pushes, and tags run validation; duplicate branch pipelines are skipped for
+pushes with an open merge request. Jobs explicitly select their Python
+interpreter rather than relying on the development `.python-version` pin.
+JUnit test reports and built distributions are retained as job artifacts.
+
+To enable publishing on GitLab:
+
+1. Use a runner that supports the configured Python Docker images.
+2. Protect release tags matching `v*` and restrict who can create them.
+3. Add `UV_PUBLISH_TOKEN` as a masked, protected CI/CD variable containing a
+   PyPI API token scoped to the `verysimpletree` project.
+4. Set the version in `pyproject.toml`, update `uv.lock`, and commit the changes.
+5. Push a matching stable version tag, such as `v2.0.0`.
+
+Publishing runs automatically only for protected stable version tags, after
+checks, tests, and the build pass. The tag must match the package version.
+The publish job uploads the build job's artifacts without rebuilding them.
+Branch and merge request pipelines never publish.
+
+## Structural mutations
+
+- `parent.add_child(child)` appends a detached child and returns it.
+- `parent.insert_child(index, child)` inserts a detached child and returns it.
+  Indices follow `list.insert()`: negative indices count from the end, and
+  out-of-range indices are clamped.
+- `parent.remove(child)` detaches a direct child.
+- `parent.replace_child(old, new, index=0)` replaces a direct child in place.
+  `old` can also be a predicate; `index` selects among matching children.
+  Replacing a child with itself is a no-op. The method returns `None`.
+
+Children must have no parent before attachment. Self-insertion, ancestor
+insertion, and attaching an already-parented child raise `ValueError`.
+Subclass child-type checks still apply. Invalid attachments leave the tree
+unchanged. To move a child, remove it from its old parent first:
+
+```python
+old_parent.remove(child)
+new_parent.add_child(child)
+```
+
+Mutation methods update parent pointers, leaf status, and affected traversal,
+leaf, and ancestor-path caches.
+
+## Subclass contract
+
+Implement `_check_child_to_be_added()` to validate allowed child types, raising
+an exception for invalid children without mutating the tree. Structural checks
+are shared by `add_child()`, `insert_child()`, and `replace_child()` through
+`_validate_child_attachment()`.
+
+Inherited structural operations use `_children` as their authoritative child
+storage. Overriding `get_children()` alone does not provide alternative-storage
+support. Subclasses using `_children` should reuse the mutation methods rather
+than assign parent pointers or edit child lists directly.
+
+`get_children()` still returns the mutable backing list for compatibility.
+Direct edits bypass validation and cache invalidation.

verysimpletree-2.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "verysimpletree"
+version = "2.0.0"
+description = "lightweight tree data structure"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[[project.authors]]
+name = "Alex Gorji"
+email = "aligorji@hotmail.com"
+
+[project.urls]
+Homepage = "https://gitlab.com/alexgorji/verysimpletree.git"
+Repository = "https://gitlab.com/alexgorji/verysimpletree.git"
+
+[dependency-groups]
+test = [
+    "mypy>=2.4.0,<3",
+    "pytest>=9.1.1,<10",
+    "pytest-xdist>=3.8.0,<4",
+    "pytest-cov>=7.1.0,<8",
+]
+dev = ["ruff>=0.17.1,<0.18"]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.uv.build-backend]
+module-root = ""
+source-include = ["verysimpletree/py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-s --doctest-modules"
+markers = [
+    "nonci: marks non ci tests",
+    "wip: marks wip tests",
+    "only: focused tests",
+]
+
+[tool.mypy]
+python_version = "3.11"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"

verysimpletree-2.0.0/pyproject.toml.orig

@@ -0,0 +1,54 @@
+[project]
+name = "verysimpletree"
+version = "2.0.0"
+description = "lightweight tree data structure"
+authors = [{ name = "Alex Gorji", email = "aligorji@hotmail.com" }]
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/alexgorji/verysimpletree.git"
+Repository = "https://gitlab.com/alexgorji/verysimpletree.git"
+
+[dependency-groups]
+test = [
+    "mypy>=2.4.0,<3",
+    "pytest>=9.1.1,<10",
+    "pytest-xdist>=3.8.0,<4",
+    "pytest-cov>=7.1.0,<8",
+]
+dev = ["ruff>=0.17.1,<0.18"]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.uv.build-backend]
+module-root = ""
+source-include = ["verysimpletree/py.typed"]
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = "-s --doctest-modules"
+markers = ["nonci: marks non ci tests", "wip: marks wip tests", "only: focused tests"]
+
+[tool.mypy]
+python_version = "3.11"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+# Preserve the lint policy used before Ruff's expanded defaults.
+select = ["E4", "E7", "E9", "F"]