visor-python 0.1.0__tar.gz

visor_python-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,90 @@
+name: Bug report
+description: Report a problem with visor-python.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this.
+
+        Please do not include API keys, secrets, or sensitive live API response data.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+      placeholder: Describe the bug clearly and briefly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Minimal code or steps that reproduce the issue.
+      render: python
+      placeholder: |
+        from visor import VisorClient
+
+        with VisorClient(api_key="...") as client:
+            ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead? Include traceback text if available.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: visor-python version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: python-version
+    attributes:
+      label: Python version
+      options:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+        - "3.13"
+        - "Other"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: client
+    attributes:
+      label: Client type
+      options:
+        - Sync VisorClient
+        - Async AsyncVisorClient
+        - Both
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other details that may help. Redact secrets and identifiers if needed.

visor_python-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/whitewalls86/visor-python/security/advisories/new
+    about: Please report security vulnerabilities privately.

visor_python-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,57 @@
+name: Feature request or API coverage
+description: Request a new SDK feature, endpoint wrapper, or model coverage.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve visor-python.
+
+        Please do not include API keys, secrets, or sensitive live API response data.
+
+  - type: textarea
+    id: goal
+    attributes:
+      label: What do you want to do?
+      description: Describe the workflow or capability you want the SDK to support.
+      placeholder: I want to...
+    validations:
+      required: true
+
+  - type: input
+    id: api-area
+    attributes:
+      label: Related Visor API area
+      description: Endpoint, resource, or SDK area if known.
+      placeholder: listings, dealers, VIN lookup, facets, usage, pagination, models
+
+  - type: textarea
+    id: proposed-api
+    attributes:
+      label: Proposed SDK API
+      description: If you have a preferred Python API shape, sketch it here.
+      render: python
+      placeholder: |
+        with VisorClient() as client:
+            result = client.some_method(...)
+
+  - type: textarea
+    id: value
+    attributes:
+      label: Why is this useful?
+      description: Explain the use case or user impact.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workaround or different API shape you considered.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links, examples, or redacted response shapes that may help.

visor_python-0.1.0/.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Chicago"
+    open-pull-requests-limit: 5
+    groups:
+      python-dev-dependencies:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+      python-runtime-dependencies:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:15"
+      timezone: "America/Chicago"
+    open-pull-requests-limit: 5

visor_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format --check
+        run: ruff format --check .
+
+      - name: mypy
+        run: mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: pytest
+        run: pytest --cov=visor --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check dist
+        run: python -m twine check dist/*

visor_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index to publish to"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

visor_python-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python caches
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / lint / type caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Claude
+.claude/
+CLAUDE.md
+
+# Docs (local reference material)
+Design Docs/
+Visor API docs/
+
+# Graphify knowledge graph outputs
+graphify-out/
+
+# Environment variables
+.env

visor_python-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check .
+        language: system
+        pass_filenames: false
+
+      - id: ruff-format-check
+        name: ruff format --check
+        entry: ruff format --check .
+        language: system
+        pass_filenames: false
+
+      - id: mypy
+        name: mypy
+        entry: mypy src
+        language: system
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        pass_filenames: false

visor_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 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] - 2026-06-13
+
+### Added
+
+- Initial package scaffold: exceptions, filter models, response models
+- `visor.exceptions` — typed exception hierarchy
+- `visor.models._base` — shared building blocks and `ListingsFilterBase`
+- `visor.models.listings` — `ListingsFilter` and listing response models
+- `visor.models.facets` — `FacetsFilter` and facet response models
+- `AsyncVisorClient` — async HTTP client with context-manager support
+- `VisorClient` — synchronous HTTP client with context-manager support
+- Auto-pagination helpers: `paginate_listings`, `paginate_dealers` (async generators),
+  `iter_listings`, `iter_dealers` (sync iterators)
+- Public export audit and test suite (`tests/test_exports.py`)
+- `src/visor/py.typed` PEP 561 marker for typed-package distribution
+- Publish-grade `pyproject.toml` metadata: authors, classifiers, keywords, license files, URLs
+- CI matrix across Python 3.10–3.13 with separate lint, test, and build jobs
+
+[Unreleased]: https://github.com/whitewalls86/visor-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/whitewalls86/visor-python/releases/tag/v0.1.0

visor_python-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want visor-python to be a welcoming, useful project for people building with
+the Visor Public API. Everyone participating in this project is expected to help
+keep the community respectful, inclusive, and focused on constructive work.
+
+## Expected Behavior
+
+Examples of behavior that helps this community:
+
+- Be respectful of different experience levels, backgrounds, and viewpoints.
+- Give and receive technical feedback with patience and specificity.
+- Assume good intent, while being willing to clarify and correct mistakes.
+- Keep discussions relevant to the project and its users.
+- Respect maintainers' time by using clear bug reports, examples, and context.
+
+## Unacceptable Behavior
+
+Examples of behavior that is not acceptable:
+
+- Harassment, intimidation, personal attacks, or discriminatory language.
+- Sexualized language or imagery in project spaces.
+- Trolling, sustained disruption, or deliberately derailing discussions.
+- Publishing private information without explicit permission.
+- Any conduct that would reasonably make participation unsafe or unwelcome.
+
+## Scope
+
+This Code of Conduct applies in project spaces, including GitHub issues, pull
+requests, discussions, documentation, and any other public or private space used
+for project work. It also applies when someone represents the project in public.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, contact the maintainer at
+miller.andrew.preston@gmail.com. Reports will be handled as respectfully and
+privately as possible.
+
+Please include:
+
+- What happened and where.
+- Any relevant links, screenshots, or context.
+- Whether immediate action is needed to keep someone safe.
+
+## Enforcement
+
+Maintainers may take any action they judge appropriate to protect the community,
+including warnings, removing comments, closing issues or pull requests,
+temporary bans, or permanent bans from project spaces.
+
+Enforcement decisions should be guided by impact, context, and the goal of
+keeping the project healthy and safe for contributors and users.
+
+## Attribution
+
+This Code of Conduct is adapted from common open source community standards,
+including the Contributor Covenant.

visor_python-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Contributions are welcome. Please open an issue before starting significant work
+so we can discuss the approach.
+
+## Setup
+
+```bash
+git clone https://github.com/whitewalls86/visor-python
+cd visor-python
+pip install -e ".[dev]"
+```
+
+## Running checks
+
+```bash
+pytest
+ruff check src/ tests/
+ruff format src/ tests/
+mypy src/
+```
+
+## Pull requests
+
+- Keep PRs focused — one logical change per PR.
+- All tests must pass and mypy must be clean before merging.
+- Add a `CHANGELOG.md` entry under `[Unreleased]`.
+
+## Versioning and releases
+
+This package follows [Semantic Versioning](https://semver.org/) and
+[PEP 440](https://peps.python.org/pep-0440/) version strings.
+
+- The package is pre-1.0 (`0.x`). Minor version bumps may include breaking changes.
+- Release tags use a `v` prefix — e.g. `v0.1.0`, `v0.2.0`.
+- After `v1.0.0`, breaking changes require a major version bump.
+- Version is set in `pyproject.toml`. Do not version-bump in a feature PR;
+  maintainers handle releases separately.

visor_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 visor-python contributors
+
+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.