nestedutils 1.1.1__tar.gz

nestedutils-1.1.1/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: ysskrishna
+patreon: ysskrishna

nestedutils-1.1.1/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Deploy Docs
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v0.1.0
+      - v*
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.8
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with MkDocs
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

nestedutils-1.1.1/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: "Publish"
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v0.1.0
+      - v*
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Install Python 3.8
+        run: uv python install 3.8
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

nestedutils-1.1.1/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest

nestedutils-1.1.1/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+workspace/

nestedutils-1.1.1/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.1]
+
+### Changed
+
+- Updated documentation badge in README to include `/nestedutils` path
+
+## [1.1.0]
+
+### Added
+
+- `exists_at()` function to check if a path exists in nested data structures
+- Safety limits: Maximum path depth (100 levels) and maximum list index (10,000) to prevent resource exhaustion
+- Comprehensive MkDocs documentation with Material theme
+- CONTRIBUTING.md guide for contributors
+- GitHub Actions workflow for automated documentation deployment
+
+### Changed
+
+- **BREAKING**: Renamed API functions for consistency:
+  - `get_path()` → `get_at()`
+  - `set_path()` → `set_at()`
+  - `del_path()` → `delete_at()`
+- Improved docstrings across all functions with detailed examples and parameter descriptions
+- Enhanced path validation with better error messages for edge cases
+- Refactored fill strategy handling using enums for better type safety
+- Updated README with improved documentation and examples
+
+### Fixed
+
+- Fixed bugs with negative index handling in `get_at()`, `set_at()`, and `delete_at()` methods
+- Improved validation in path normalization function
+- Fixed edge cases with empty paths and empty keys
+
+## [1.0.1]
+
+### Added
+
+- GitHub Actions workflow enhancement to automatically create releases on publish
+
+### Changed
+
+- Updated package description for better clarity and discoverability
+- Expanded keywords in `pyproject.toml` for improved PyPI searchability
+- Updated README with enhanced description and OG image
+
+## [1.0.0]
+
+### Added
+
+- Initial release of nestedutils
+- `get_path()` function for accessing nested values in dictionaries, lists
+- `set_path()` function for setting nested values with automatic container creation
+- `del_path()` function for deleting nested values
+- Support for dot-notation string paths (`"a.b.c"`) and list paths (`["a", "b", "c"]`)
+- List index support with positive and negative indices
+- Multiple fill strategies for `set_path()`:
+  - `"auto"`: Intelligently creates containers based on next key type
+  - `"none"`: Fills missing list items with `None`
+  - `"dict"`: Always creates dictionaries
+  - `"list"`: Always creates lists
+- Comprehensive error handling with `PathError` exception and `PathErrorCode` enum
+- Support for navigating through `None` values (replaces with appropriate containers)
+- Sparse list creation when setting values at high indices
+- Full test coverage with comprehensive test suite
+
+### Features
+
+- Zero external dependencies
+- Python 3.8+ compatibility
+- Immutable container protection (tuples cannot be modified)
+- Safe list deletion (requires explicit `allow_list_mutation=True` flag)
+
+[1.1.1]: https://github.com/ysskrishna/nestedutils/releases/tag/v1.1.1
+[1.1.0]: https://github.com/ysskrishna/nestedutils/releases/tag/v1.1.0
+[1.0.1]: https://github.com/ysskrishna/nestedutils/releases/tag/v1.0.1
+[1.0.0]: https://github.com/ysskrishna/nestedutils/releases/tag/v1.0.0

nestedutils-1.1.1/CONTRIBUTING.md

@@ -0,0 +1,244 @@
+# Contributing Guide
+
+Thank you for your interest in contributing to `nestedutils`! This guide will help you get started with development and understand how to contribute effectively.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Code Style](#code-style)
+- [Building the Package](#building-the-package)
+- [Documentation](#documentation)
+- [Additional Resources](#additional-resources)
+
+## Code of Conduct
+
+This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful, inclusive, and constructive in all interactions.
+
+## Getting Started
+
+Before you begin, make sure you have:
+
+- Python 3.8 or higher
+- [uv](https://github.com/astral-sh/uv) - A fast Python package installer and resolver
+- Git installed and configured
+
+## Development Setup
+
+### Installing uv
+
+If you don't have `uv` installed, you can install it using [UV Getting Started](https://docs.astral.sh/uv/getting-started/installation/)
+
+### Setting Up the Development Environment
+
+1. Fork the repository on GitHub
+
+2. Clone your fork locally:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/nestedutils.git
+cd nestedutils
+```
+
+3. Add the upstream repository:
+
+```bash
+git remote add upstream https://github.com/ysskrishna/nestedutils.git
+```
+
+4. Install the project and development dependencies using `uv`:
+
+```bash
+uv sync --dev
+```
+
+This will:
+- Create a virtual environment (if it doesn't exist)
+- Install the project in editable mode
+- Install all development dependencies (including `pytest` and documentation tools)
+
+## Making Changes
+
+1. Create a new branch for your changes:
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix-name
+```
+
+2. Make your changes following the [Code Style](#code-style) guidelines
+
+3. Write or update tests for your changes (see [Testing](#testing))
+
+4. Ensure all tests pass and the code is properly formatted
+
+## Testing
+
+### Running Tests
+
+Run all tests using pytest:
+
+```bash
+uv run pytest
+```
+
+### Running Specific Test Files
+
+```bash
+uv run pytest tests/test_get.py
+```
+
+### Running Specific Test Functions
+
+```bash
+uv run pytest tests/test_get.py::test_get_at_basic
+```
+
+### Test Coverage
+
+Make sure your changes include appropriate test coverage. All new features should have corresponding tests.
+
+### Writing Tests
+
+- Place tests in the `tests/` directory
+- Follow the existing test file naming convention (`test_*.py`)
+- Test both success cases and error cases
+- Include edge cases when relevant
+
+## Submitting Changes
+
+1. **Update Documentation**: If you've added new features or changed behavior, update the relevant documentation:
+   - Update `README.md` if the API or usage has changed
+   - Update `CHANGELOG.md` with a description of your changes
+   - Update docstrings if you've modified functions
+
+2. **Commit Your Changes**: Write clear, descriptive commit messages:
+
+```bash
+git add .
+git commit -m "Add feature: description of what you added"
+```
+
+Good commit messages:
+- Start with a verb in imperative mood (e.g., "Add", "Fix", "Update")
+- Be concise but descriptive
+- Reference issue numbers if applicable (e.g., "Fix #123: description")
+
+3. **Push to Your Fork**:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+4. **Create a Pull Request**:
+   - Go to the original repository on GitHub
+   - Click "New Pull Request"
+   - Select your fork and branch
+   - Fill out the PR template with:
+     - Description of changes
+     - Related issues (if any)
+     - Testing performed
+     - Any breaking changes
+
+5. **Respond to Feedback**: Be open to feedback and ready to make changes if requested
+
+## Code Style
+
+### General Guidelines
+
+- Follow PEP 8 style guidelines
+- Use meaningful variable and function names
+- Keep functions focused and single-purpose
+- Add docstrings to all public functions and classes
+- Keep lines under 100 characters when possible
+
+### Type Hints
+
+- Use type hints for function parameters and return values
+- The project includes a `py.typed` marker file, so type hints are important
+
+### Documentation
+
+- Use clear, concise docstrings
+- Follow the existing docstring format in the codebase
+- Include parameter descriptions and return value descriptions
+- Add examples for complex functions
+
+### Import Organization
+
+- Group imports: standard library, third-party, local
+- Use absolute imports
+- Keep imports at the top of the file
+
+## Building the Package
+
+To build the package locally:
+
+```bash
+uv build
+```
+
+This will create distribution files in the `dist/` directory:
+- `nestedutils-<version>-py3-none-any.whl` (wheel)
+- `nestedutils-<version>.tar.gz` (source distribution)
+
+### Installing the Local Package
+
+To test the package installation locally:
+
+```bash
+# Install from the built wheel
+uv pip install dist/nestedutils-*.whl
+
+# Or install in editable mode for development
+uv pip install -e .
+```
+
+## Documentation
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://github.com/squidfunk/mkdocs-material) for documentation.
+
+### Serving Documentation Locally
+
+To preview the documentation locally with live reload:
+
+```bash
+uv run mkdocs serve
+```
+
+This will start a local development server (usually at `http://127.0.0.1:8000`) that automatically reloads when you make changes to the documentation files.
+
+### Building Documentation
+
+To build the documentation as static HTML files:
+
+```bash
+uv run mkdocs build
+```
+
+This will create a `site/` directory containing the static HTML files ready for deployment.
+
+## Additional Resources
+
+- [uv Documentation](https://docs.astral.sh/uv/)
+- [pytest Documentation](https://docs.pytest.org/)
+- [Python Packaging Guide](https://packaging.python.org/)
+- [PEP 8 Style Guide](https://pep8.org/)
+- [Type Hints Documentation](https://docs.python.org/3/library/typing.html)
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://github.com/squidfunk/mkdocs-material)
+
+## Questions?
+
+If you have questions or need help, feel free to:
+- Open an issue on GitHub
+- Check existing issues and discussions
+- Review the codebase and documentation
+
+Thank you for contributing to `nestedutils`! 🎉
+

nestedutils-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Y. Siva Sai Krishna
+
+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.