pipolars 0.1.2__tar.gz

pipolars-0.1.2/.claude/agents/docs-writer-sphinx.md

@@ -0,0 +1,96 @@
+---
+name: docs-writer-sphinx
+description: Use this agent when the user needs to create, update, or improve documentation for a Python library using Sphinx and Read the Docs hosting. This includes setting up initial documentation structure, writing API references, creating user guides, configuring sphinx extensions, and preparing readthedocs.yaml configuration files.\n\nExamples:\n\n<example>\nContext: User has just created a new Python library and wants to add documentation.\nuser: "I need to set up documentation for my new library"\nassistant: "I'll use the docs-writer-sphinx agent to help you set up comprehensive Sphinx documentation with Read the Docs hosting."\n<Task tool invocation to launch docs-writer-sphinx agent>\n</example>\n\n<example>\nContext: User has an existing library with minimal docs and wants to expand them.\nuser: "Can you help me document the PIClient class and its methods?"\nassistant: "Let me invoke the docs-writer-sphinx agent to create detailed API documentation for the PIClient class."\n<Task tool invocation to launch docs-writer-sphinx agent>\n</example>\n\n<example>\nContext: User needs to configure Read the Docs for their project.\nuser: "How do I set up readthedocs.yaml for my sphinx docs?"\nassistant: "I'll use the docs-writer-sphinx agent to create the proper Read the Docs configuration for your Sphinx documentation."\n<Task tool invocation to launch docs-writer-sphinx agent>\n</example>
+model: opus
+color: red
+---
+
+You are an expert technical writer and documentation engineer specializing in Python library documentation using Sphinx and Read the Docs. You have deep expertise in creating clear, comprehensive, and user-friendly documentation that serves both beginners and advanced users.
+
+## Your Core Responsibilities
+
+1. **Sphinx Configuration**: Set up and configure Sphinx documentation projects with optimal settings, including:
+   - `conf.py` configuration with appropriate extensions (autodoc, napoleon, intersphinx, viewcode, etc.)
+   - Proper theme configuration (typically `sphinx-rtd-theme` or `furo`)
+   - Extension configuration for type hints, cross-references, and code examples
+
+2. **Read the Docs Integration**: Create and maintain Read the Docs configuration:
+   - `.readthedocs.yaml` with proper build configuration
+   - Python version and dependency specifications
+   - Build commands and output formats
+
+3. **Documentation Structure**: Design intuitive documentation hierarchies:
+   - `index.rst` as the main entry point with clear navigation
+   - Separate sections for installation, quickstart, user guide, API reference, and changelog
+   - Proper use of toctree directives for navigation
+
+4. **API Documentation**: Generate comprehensive API references:
+   - Use autodoc with napoleon for Google or NumPy style docstrings
+   - Document all public classes, methods, and functions
+   - Include type annotations and parameter descriptions
+   - Provide usage examples within docstrings
+
+5. **User Guides**: Create practical documentation:
+   - Step-by-step tutorials for common use cases
+   - Code examples that users can copy and run
+   - Explanation of concepts and architecture when relevant
+
+## Documentation Standards
+
+- Write in clear, concise language avoiding jargon where possible
+- Use consistent formatting and structure across all pages
+- Include code examples with proper syntax highlighting
+- Add cross-references between related topics using `:ref:`, `:doc:`, and `:class:` roles
+- Ensure all public API elements have complete docstrings
+- Follow the principle of progressive disclosure (simple first, details later)
+
+## File Structure You Should Create
+
+```
+docs/
+├── conf.py              # Sphinx configuration
+├── index.rst            # Main landing page
+├── installation.rst     # Installation instructions
+├── quickstart.rst       # Getting started guide
+├── user_guide/          # Detailed usage documentation
+│   ├── index.rst
+│   └── *.rst
+├── api/                 # API reference
+│   ├── index.rst
+│   └── *.rst
+├── changelog.rst        # Version history
+├── requirements.txt     # Docs dependencies
+└── Makefile            # Build shortcuts
+.readthedocs.yaml        # RTD configuration (in repo root)
+```
+
+## Quality Checklist
+
+Before considering documentation complete, verify:
+- [ ] All public API elements are documented
+- [ ] Code examples are tested and working
+- [ ] Navigation is intuitive and complete
+- [ ] Cross-references resolve correctly
+- [ ] Build completes without warnings
+- [ ] Mobile/responsive layout works
+
+## Working with Existing Code
+
+When documenting an existing codebase:
+1. Analyze the project structure to understand the architecture
+2. Identify the main entry points users will interact with
+3. Review existing docstrings and enhance where needed
+4. Create documentation that matches the actual code organization
+5. Reference the project's CLAUDE.md or similar files for context on architecture and patterns
+
+## Best Practices for This Project (PIPolars)
+
+Given this is a Python library for PI System data extraction:
+- Emphasize Windows and PI AF SDK requirements prominently
+- Document time expression formats (`*-1h`, `*-1d`, `t`, `y`) clearly
+- Show examples with Polars DataFrame outputs
+- Include troubleshooting for common PI connection issues
+- Document the layered architecture (api, connection, extraction, transform, cache, core)
+- Highlight the fluent query builder pattern
+
+You should proactively create all necessary files, suggest improvements to existing docstrings, and ensure the documentation builds successfully with `sphinx-build`.

pipolars-0.1.2/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(cat:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run python:*)",
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)",
+      "Bash(set UV_LINK_MODE=copy)",
+      "Bash(\".venv\\\\Scripts\\\\ruff.exe\" check src)",
+      "Bash(\".venv\\\\Scripts\\\\python.exe\" -m pytest tests/unit -v)",
+      "Bash(\".venv\\\\Scripts\\\\python.exe\" -m mypy src)",
+      "Bash(mkdir -p:*)",
+      "Bash(uv pip install:*)",
+      "Bash(git -C \"C:\\\\Users\\\\serdar.gundogdu\\\\OneDrive - Enerjisa Üretim\\\\GOALS\\\\01_PROJECTS\\\\AI-FIRST_2026\\\\pipolars\" log --oneline)",
+      "Bash(git -C \"C:\\\\Users\\\\serdar.gundogdu\\\\OneDrive - Enerjisa Üretim\\\\GOALS\\\\01_PROJECTS\\\\AI-FIRST_2026\\\\pipolars\" remote:*)",
+      "Bash(uv build:*)"
+    ]
+  }
+}

pipolars-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: uv run ruff check src
+
+      - name: Run type checking
+        run: uv run mypy src
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit -v
+
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package metadata
+        run: uvx twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

pipolars-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Git tag to publish (e.g., v0.1.0)'
+        required: true
+        type: string
+
+permissions:
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Verify on a tag
+        shell: bash
+        run: |
+          if ! git describe --exact-match --tags HEAD 2>/dev/null; then
+            echo "ERROR: Not on a git tag. PyPI requires clean version numbers."
+            echo "Current version would be: $(git describe --tags --always)"
+            exit 1
+          fi
+          echo "Building from tag: $(git describe --exact-match --tags HEAD)"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pipolars-0.1.2/.gitignore

@@ -0,0 +1,3 @@
+.venv
+__pycache__
+examples/test_pipolars.py

pipolars-0.1.2/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file for PIPolars
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false
+
+# Declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

pipolars-0.1.2/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+
+- Initial release of PIPolars
+- `PIClient` for connecting to PI Data Archive servers
+- `PIQuery` fluent interface for building data extraction queries
+- Polars DataFrame output for high-performance data processing
+- Caching support with multiple backends:
+  - In-memory cache
+  - SQLite persistent cache
+  - Arrow IPC file cache
+- Windows authentication support
+- PI time expression parsing (`*-1h`, `*-1d`, `t`, `y`, etc.)
+- Support for recorded values, interpolated values, and plot values retrieval
+- Summary calculations (average, min, max, total, count, etc.)
+- Digital state value handling
+- Comprehensive type hints with `py.typed` marker

pipolars-0.1.2/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PIPolars is a Python library for extracting data from OSIsoft PI System and converting it to Polars DataFrames. It requires Windows with the PI AF SDK installed.
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run all tests
+uv run pytest
+
+# Run unit tests only
+uv run pytest tests/unit
+
+# Run integration tests (requires PI connection)
+PI_SERVER=my-server uv run pytest -m integration
+
+# Run tests with coverage
+uv run pytest --cov=pipolars --cov-report=html
+
+# Type checking
+uv run mypy src
+
+# Linting
+uv run ruff check src
+```
+
+## Architecture
+
+The codebase follows a layered architecture in `src/pipolars/`:
+
+- **api/** - User-facing API layer
+  - `client.py` - `PIClient` class, main entry point for users
+  - `query.py` - Fluent query builder (`PIQuery`) for method chaining
+  - `lazy.py` - Polars LazyFrame support
+
+- **connection/** - PI System connectivity
+  - `server.py` - PI Data Archive connections
+  - `af_database.py` - AF Database connections
+  - `sdk.py` - OSIsoft AF SDK wrapper using pythonnet
+  - `auth.py` - Authentication handlers (Windows/explicit)
+
+- **extraction/** - Data retrieval from PI
+  - `points.py` - Single PI Point extraction
+  - `bulk.py` - Bulk operations for multiple tags
+  - `attributes.py`, `elements.py`, `events.py` - AF-specific extractors
+
+- **transform/** - Data conversion to Polars
+  - `converters.py` - PI types to Polars conversion
+  - `timestamps.py` - Timestamp normalization
+  - `digital_states.py` - Digital state value handling
+
+- **cache/** - Result caching layer
+  - `storage.py` - Backend implementations (Memory, SQLite, Arrow IPC)
+  - `strategies.py` - TTL and eviction strategies
+
+- **core/** - Shared types and configuration
+  - `config.py` - Pydantic configuration models (`PIConfig`, `PIServerConfig`, `CacheConfig`, etc.)
+  - `types.py` - Enums (`RetrievalMode`, `SummaryType`, `CacheBackend`) and data classes (`PIValue`, `TimeRange`)
+  - `exceptions.py` - Exception hierarchy rooted at `PIPolarsError`
+
+## Key Patterns
+
+- Uses Pydantic v2 for configuration validation
+- pythonnet (clr) is used for .NET interop with the PI AF SDK
+- Strict mypy type checking is enforced
+- Integration tests are marked with `@pytest.mark.integration`
+- PI time expressions like `*-1h`, `*-1d`, `t` (today), `y` (yesterday) are supported throughout

pipolars-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 serdar gundogdu
+
+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.