pkgdb 0.1.0__tar.gz

pkgdb-0.1.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# 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).
+
+## [0.1.4]
+
+### Added
+
+- HTML report enhancements:
+  - `pkgdb report <package>` generates detailed single-package report with download stats, history chart, Python version and OS distribution pie charts
+  - `pkgdb report -e` includes aggregated Python version and OS distribution summary in the main report
+- New functions: `make_svg_pie_chart`, `aggregate_env_stats`, `generate_package_html_report`
+- 14 new tests for pie charts, environment aggregation, and package reports (69 total)
+
+## [0.1.3]
+
+### Added
+
+- `stats` command for detailed package statistics:
+  - Python version distribution with visual bars
+  - Operating system breakdown (Linux, Windows, Darwin)
+  - Download summary (total, month, week, day)
+- New functions: `fetch_python_versions`, `fetch_os_stats`
+
+### Note
+
+- Per-version (package version) downloads not available through pypistats API
+
+## [0.1.2]
+
+### Added
+
+- `export` command with support for multiple formats:
+  - CSV (`pkgdb export -f csv`)
+  - JSON (`pkgdb export -f json`)
+  - Markdown (`pkgdb export -f markdown`)
+- Export to file with `-o` option or stdout by default
+- New functions: `export_csv`, `export_json`, `export_markdown`
+
+## [0.1.1]
+
+### Added
+
+- `history` command to view historical stats for a specific package
+- Growth metrics (month-over-month percentage change) in `list` output
+- Sparkline trend indicators in `list` output
+- Time-series chart in HTML report showing downloads over time (top 5 packages)
+- New functions: `get_package_history`, `get_all_history`, `calculate_growth`, `make_sparkline`
+
+### Changed
+
+- `list` command now shows trend sparklines and growth percentages
+- HTML report now includes "Downloads Over Time" chart when historical data available
+
+## [0.1.0]
+
+### Added
+
+- Initial release
+- CLI commands: `fetch`, `list`, `report`, `update`
+- SQLite database storage for historical stats
+- HTML report generation with SVG visualizations
+- YAML-based package configuration (`packages.yml`)
+- Support for custom database and packages file paths
+- Pytest test suite with 24 tests covering:
+  - Database operations
+  - Package loading from YAML
+  - Statistics storage and retrieval
+  - HTML report generation
+  - CLI argument parsing

pkgdb-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 Shakeeb Alireza
+
+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.

pkgdb-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: pkgdb
+Version: 0.1.0
+Summary: Track, store and query your PyPI package download statistics
+Keywords: pypi,statistics,downloads,analytics,cli
+Author: Shakeeb Alireza
+Author-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Libraries :: Python Modules
+Classifier: Topic :: System :: Software Distribution
+Requires-Dist: pypistats>=1.12.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tabulate>=0.9.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/shakfu/pkgdb
+Project-URL: Repository, https://github.com/shakfu/pkgdb
+Project-URL: Issues, https://github.com/shakfu/pkgdb/issues
+Description-Content-Type: text/markdown
+
+# pkgdb
+
+Track PyPI package download statistics. Fetches download stats via the pypistats API, stores historical data in SQLite, and generates HTML reports with charts.
+
+## Installation
+
+```sh
+pip install pkgdb
+```
+
+To build:
+
+Requires Python 3.10+. Uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Configure packages
+
+Edit `packages.yml` to list the packages you want to track:
+
+```yaml
+published:
+  - my-package
+  - another-package
+```
+
+### Commands
+
+```bash
+# Fetch latest stats from PyPI and store in database
+pkgdb fetch
+
+# Display stats in terminal (includes trend sparklines and growth %)
+pkgdb list
+
+# Show historical stats for a specific package
+pkgdb history <package-name>
+
+# Generate HTML report with charts (opens in browser)
+pkgdb report
+
+# Generate detailed HTML report for a single package
+pkgdb report <package-name>
+
+# Include environment summary (Python versions, OS) in report
+pkgdb report -e
+
+# Export stats in various formats
+pkgdb export -f csv      # CSV format (default)
+pkgdb export -f json     # JSON format
+pkgdb export -f markdown # Markdown table
+
+# Show detailed stats for a package (Python versions, OS breakdown)
+pkgdb stats <package-name>
+
+# Fetch stats and generate report in one step
+pkgdb update
+```
+
+### Options
+
+```bash
+# Use custom database file
+pkgdb -d custom.db fetch
+
+# Use custom packages file
+pkgdb -p custom.yml fetch
+
+# Specify output file for report
+pkgdb report -o custom-report.html
+
+# Limit history output to N days
+pkgdb history my-package -n 14
+
+# Export to file instead of stdout
+pkgdb export -f json -o stats.json
+```
+
+## Architecture
+
+Single-file CLI application with seven commands:
+
+- **fetch**: Calls `pypistats.recent()` and `pypistats.overall()` for each package, stores results in SQLite
+- **list**: Queries latest stats per package with trend sparklines and growth metrics
+- **history**: Shows historical data for a specific package over time
+- **report**: Generates self-contained HTML report with SVG charts (bar charts + time-series). With `-e` flag, includes Python version and OS distribution summary. With package argument, generates detailed single-package report
+- **export**: Exports stats in CSV, JSON, or Markdown format
+- **stats**: Shows detailed breakdown (Python versions, OS) for a single package
+- **update**: Runs fetch then report
+
+### Data flow
+
+```
+packages.yml -> pypistats API -> SQLite (pkg.db) -> HTML/terminal output
+```
+
+### Database schema
+
+The `package_stats` table stores:
+- `package_name`: Package identifier
+- `fetch_date`: Date stats were fetched (YYYY-MM-DD)
+- `last_day`, `last_week`, `last_month`: Recent download counts
+- `total`: Total downloads (excluding mirrors)
+
+Stats are upserted per package per day, so running fetch multiple times on the same day updates rather than duplicates.
+
+## Files
+
+- `pkgdb.py`: Main CLI application
+- `packages.yml`: Package list configuration
+- `pkg.db`: SQLite database (auto-created)
+- `report.html`: Generated HTML report (default output)
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+pytest
+
+# Run tests with verbose output
+pytest -v
+```
+
+## Dependencies
+
+Runtime:
+- `pypistats`: PyPI download statistics API client
+- `pyyaml`: YAML configuration parsing
+- `tabulate`: Terminal table formatting
+
+Development:
+- `pytest`: Testing framework

pkgdb-0.1.0/README.md

@@ -0,0 +1,139 @@
+# pkgdb
+
+Track PyPI package download statistics. Fetches download stats via the pypistats API, stores historical data in SQLite, and generates HTML reports with charts.
+
+## Installation
+
+```sh
+pip install pkgdb
+```
+
+To build:
+
+Requires Python 3.10+. Uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Configure packages
+
+Edit `packages.yml` to list the packages you want to track:
+
+```yaml
+published:
+  - my-package
+  - another-package
+```
+
+### Commands
+
+```bash
+# Fetch latest stats from PyPI and store in database
+pkgdb fetch
+
+# Display stats in terminal (includes trend sparklines and growth %)
+pkgdb list
+
+# Show historical stats for a specific package
+pkgdb history <package-name>
+
+# Generate HTML report with charts (opens in browser)
+pkgdb report
+
+# Generate detailed HTML report for a single package
+pkgdb report <package-name>
+
+# Include environment summary (Python versions, OS) in report
+pkgdb report -e
+
+# Export stats in various formats
+pkgdb export -f csv      # CSV format (default)
+pkgdb export -f json     # JSON format
+pkgdb export -f markdown # Markdown table
+
+# Show detailed stats for a package (Python versions, OS breakdown)
+pkgdb stats <package-name>
+
+# Fetch stats and generate report in one step
+pkgdb update
+```
+
+### Options
+
+```bash
+# Use custom database file
+pkgdb -d custom.db fetch
+
+# Use custom packages file
+pkgdb -p custom.yml fetch
+
+# Specify output file for report
+pkgdb report -o custom-report.html
+
+# Limit history output to N days
+pkgdb history my-package -n 14
+
+# Export to file instead of stdout
+pkgdb export -f json -o stats.json
+```
+
+## Architecture
+
+Single-file CLI application with seven commands:
+
+- **fetch**: Calls `pypistats.recent()` and `pypistats.overall()` for each package, stores results in SQLite
+- **list**: Queries latest stats per package with trend sparklines and growth metrics
+- **history**: Shows historical data for a specific package over time
+- **report**: Generates self-contained HTML report with SVG charts (bar charts + time-series). With `-e` flag, includes Python version and OS distribution summary. With package argument, generates detailed single-package report
+- **export**: Exports stats in CSV, JSON, or Markdown format
+- **stats**: Shows detailed breakdown (Python versions, OS) for a single package
+- **update**: Runs fetch then report
+
+### Data flow
+
+```
+packages.yml -> pypistats API -> SQLite (pkg.db) -> HTML/terminal output
+```
+
+### Database schema
+
+The `package_stats` table stores:
+- `package_name`: Package identifier
+- `fetch_date`: Date stats were fetched (YYYY-MM-DD)
+- `last_day`, `last_week`, `last_month`: Recent download counts
+- `total`: Total downloads (excluding mirrors)
+
+Stats are upserted per package per day, so running fetch multiple times on the same day updates rather than duplicates.
+
+## Files
+
+- `pkgdb.py`: Main CLI application
+- `packages.yml`: Package list configuration
+- `pkg.db`: SQLite database (auto-created)
+- `report.html`: Generated HTML report (default output)
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync
+
+# Run tests
+pytest
+
+# Run tests with verbose output
+pytest -v
+```
+
+## Dependencies
+
+Runtime:
+- `pypistats`: PyPI download statistics API client
+- `pyyaml`: YAML configuration parsing
+- `tabulate`: Terminal table formatting
+
+Development:
+- `pytest`: Testing framework

pkgdb-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "pkgdb"
+version = "0.1.0"
+description = "Track, store and query your PyPI package download statistics"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+    { name = "Shakeeb Alireza", email = "shakfu@users.noreply.github.com" }
+]
+keywords = ["pypi", "statistics", "downloads", "analytics", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Software Distribution",
+]
+dependencies = [
+    "pypistats>=1.12.0",
+    "pyyaml>=6.0.3",
+    "tabulate>=0.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shakfu/pkgdb"
+Repository = "https://github.com/shakfu/pkgdb"
+Issues = "https://github.com/shakfu/pkgdb/issues"
+
+[project.scripts]
+pkgdb = "pkgdb:main"
+
+[dependency-groups]
+dev = [
+    "build>=1.2.0",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.13",
+    "twine>=6.1.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["CHANGELOG.md", "tests"]