openmatchkit 0.2.1__tar.gz

openmatchkit-0.2.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report something that is not working
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## What happened?
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+## Environment
+
+- Python version:
+- openmatchkit version:
+- Operating system:
+
+## Extra context
+
+Please do not paste private tokens, cookies, credentials, or private source data.

openmatchkit-0.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Source policy
+    url: https://github.com/patilprashan246/openmatchkit/blob/main/DATA_SOURCES.md
+    about: Read the source and scraping policy before proposing adapters.

openmatchkit-0.2.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Feature
+
+## Why is this useful?
+
+## Suggested API or CLI
+
+```python
+
+```
+
+## Source/legal notes
+
+Does this require data from a third-party source? If yes, include public terms/licensing context.

openmatchkit-0.2.1/.github/ISSUE_TEMPLATE/source_adapter.md

@@ -0,0 +1,25 @@
+---
+name: Source adapter
+about: Propose or implement a public data source adapter
+title: "[Source]: "
+labels: source, help wanted
+assignees: ""
+---
+
+## Source
+
+## Data provided
+
+- Fixtures:
+- Results:
+- Live scores:
+- Scoreboards:
+- Player stats:
+
+## Terms and robots.txt
+
+Link source terms and robots.txt here.
+
+## Test strategy
+
+Adapters should use saved fixtures in CI, not live network calls.

openmatchkit-0.2.1/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+## Tests
+
+- [ ] `ruff check .`
+- [ ] `ruff format --check .`
+- [ ] `pytest`
+
+## Source Safety
+
+- [ ] No private, paid, login-only, or protected data source is used.
+- [ ] Source attribution is included when data is fetched or parsed.
+- [ ] New adapters use saved fixtures in tests.

openmatchkit-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Test
+        run: pytest

openmatchkit-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openmatchkit-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+.venv/
+venv/
+.env
+.DS_Store
+project details.txt

openmatchkit-0.2.1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## v0.2.1 - 2026-06-12
+
+- Added GitHub Actions trusted publishing workflow for PyPI.
+- Added README badges, roadmap, security policy, issue templates, and PR template.
+- Improved project onboarding and GitHub discoverability.
+
+## v0.2.0 - 2026-06-12
+
+- Added rich scoreboard models for clock, events, lineups, team stats, and player stats.
+- Added `PlayerHistory` models and aggregation from detailed source data.
+- Added `JsonFileSource` for authorized/public detailed JSON feeds and saved fixtures.
+- Added CLI commands:
+  - `openmatch next-match`
+  - `openmatch scoreboards`
+  - `openmatch scoreboard`
+  - `openmatch live-scoreboards`
+  - `openmatch player-history`
+- Added publish-ready wheel and source distribution checks.
+
+## v0.1.0 - 2026-06-12
+
+- Initial package structure.
+- Added OpenFootball adapter.
+- Added Football-Data.co.uk CSV adapter.
+- Added safe HTTP client with robots.txt checks, caching, and rate limiting.
+- Added fixtures, results, live score interface, standings, exports, CLI, and prediction baseline.
+- Added tests, docs, source policy, privacy policy, MIT license, and CI.

openmatchkit-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Code of Conduct
+
+openmatchkit is for education, research, and practical public-data tooling. Keep contributions respectful, source-aware, and honest about limitations.
+
+Expected behavior:
+
+- Be considerate in issues, reviews, and discussions.
+- Credit sources clearly.
+- Avoid misleading claims about official data, real-time quality, or prediction accuracy.
+- Respect privacy, copyright, and source access rules.
+
+Unacceptable behavior:
+
+- Harassment or personal attacks.
+- Attempts to add bypasses for access controls, paywalls, CAPTCHA, private APIs, or protected feeds.
+- Misrepresentation of third-party data or affiliation.
+
+Maintainers may remove contributions or discussion that conflict with these rules.

openmatchkit-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for helping improve openmatchkit.
+
+## Source adapter rules
+
+Adapters must:
+
+1. Respect source Terms of Service.
+2. Respect robots.txt.
+3. Avoid login-only, paid, private, or protected endpoints.
+4. Avoid bypassing CAPTCHA, paywalls, anti-bot systems, geoblocks, or tokens.
+5. Use caching and reasonable request rates.
+6. Return source URL and fetched timestamp.
+7. Include tests using saved fixtures, not live website calls in CI.
+8. Avoid copyrighted media, articles, video, logos, and images.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format .
+pytest
+python -m build
+```
+
+## Prediction models
+
+Prediction features must be documented as educational baselines. Do not market predictions as guaranteed outcomes, betting advice, financial advice, or professional advice.

openmatchkit-0.2.1/DATA_SOURCES.md

@@ -0,0 +1,82 @@
+# Data Sources
+
+This project separates the MIT license for code from third-party data-source terms. Do not assume a source is open licensed just because it is public or free to download.
+
+## OpenFootball
+
+Links:
+
+- https://github.com/openfootball/football.json
+- https://github.com/openfootball/worldcup.json
+
+Use:
+
+- Historical fixtures
+- Historical results
+- World Cup datasets
+- Demo and test-friendly schemas
+
+Notes:
+
+- Preferred source for the default adapter.
+- Upstream repositories describe their data as public domain or CC0 depending on repository.
+- The adapter fetches from source and includes source URL plus fetch timestamp on each match.
+
+## Football-Data.co.uk
+
+Link:
+
+- https://www.football-data.co.uk/
+
+Use:
+
+- Historical CSV results
+- Prediction experiments
+- Match statistics available in the public CSV files
+
+Notes:
+
+- Keep this as an optional adapter.
+- Do not bundle or redistribute the site's CSV files in this repository.
+- Users should check the current website terms before using downloaded data beyond local research or development.
+
+## Public HTML Pages
+
+Use:
+
+- Best-effort live scores
+- Public facts only, such as teams, score, match date, status, and venue
+- Public player sporting facts only when the source terms allow it
+
+Rules for public HTML adapters:
+
+1. Respect the source Terms of Service.
+2. Respect robots.txt.
+3. Do not bypass login, CAPTCHA, paywalls, geoblocks, tokens, or anti-bot systems.
+4. Do not copy images, logos, articles, video, protected feeds, or copyrighted media.
+5. Use caching and low request rates.
+6. Include source URL and fetched timestamp.
+7. Use saved HTML fixtures in tests instead of live requests in CI.
+8. Do not collect private personal data, contact data, sensitive data, or non-public player information.
+
+## Local Detailed JSON
+
+Use:
+
+- Authorized public feeds
+- Saved fixture data for demos and tests
+- Scoreboards, lineups, match events, team stats, player match stats, and player histories
+
+Notes:
+
+- `JsonFileSource` performs no network requests.
+- It is the safest way to integrate detailed data that users are allowed to store and process.
+- The package schema accepts optional fields so sources can return only the facts they lawfully provide.
+
+Relevant standard:
+
+- https://www.rfc-editor.org/rfc/rfc9309
+
+## Non-affiliation
+
+openmatchkit is not affiliated with, endorsed by, or sponsored by FIFA, any football federation, league, club, broadcaster, sportsbook, or data provider.

openmatchkit-0.2.1/LICENSE

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

openmatchkit-0.2.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: openmatchkit
+Version: 0.2.1
+Summary: Unofficial open-source football match data toolkit using public sources.
+Project-URL: Homepage, https://github.com/patilprashan246/openmatchkit
+Project-URL: Repository, https://github.com/patilprashan246/openmatchkit
+Project-URL: Issues, https://github.com/patilprashan246/openmatchkit/issues
+Author: Prashant Patil
+License: MIT License
+Keywords: cli,fixtures,football,open-data,prediction,scores,soccer,world-cup
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT 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
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openmatchkit
+
+[![CI](https://github.com/patilprashan246/openmatchkit/actions/workflows/ci.yml/badge.svg)](https://github.com/patilprashan246/openmatchkit/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/patilprashan246/openmatchkit)](https://github.com/patilprashan246/openmatchkit/releases)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Unofficial open-source football match data toolkit for fixtures, results, best-effort live score adapters, standings, exports, and simple prediction models.
+
+> This project is unofficial and not affiliated with FIFA, any league, club, broadcaster, federation, or data provider. It does not provide official FIFA data.
+
+## Why openmatchkit?
+
+openmatchkit gives Python developers a clean, source-attributed way to work with public football match facts without paid API keys. It starts with open/public datasets, keeps scraping optional and conservative, and returns structured JSON-ready models.
+
+## Install
+
+```bash
+pip install git+https://github.com/patilprashan246/openmatchkit.git
+```
+
+For a pinned release:
+
+```bash
+pip install git+https://github.com/patilprashan246/openmatchkit.git@v0.2.1
+```
+
+For local development:
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+pytest
+```
+
+## Quick Start
+
+```python
+from openmatchkit import MatchClient
+
+client = MatchClient()
+next_match = client.next_match(competition="worldcup", season="2026")
+
+print(next_match.model_dump(mode="json"))
+```
+
+```bash
+openmatch next-match --competition worldcup --season 2026
+```
+
+## Python API
+
+```python
+from openmatchkit import MatchClient
+
+client = MatchClient()
+
+fixtures = client.fixtures(competition="worldcup", season="2026")
+results = client.results(competition="worldcup", season="2026")
+live = client.live_scores()
+next_match = client.next_match(competition="worldcup", season="2026")
+prediction = client.predict(home="Mexico", away="South Africa", history=results)
+
+client.export_json(fixtures, "fixtures.json")
+client.export_csv(fixtures, "fixtures.csv")
+```
+
+League datasets from OpenFootball can be fetched with codes such as:
+
+```python
+matches = client.fixtures(competition="en.1", season="2015-16")
+```
+
+## CLI
+
+```bash
+openmatch fixtures --competition worldcup --season 2026
+openmatch results --competition en.1 --season 2015-16 --format csv --output results.csv
+openmatch next-match --competition worldcup --season 2026
+openmatch standings --competition worldcup --season 2026
+openmatch predict --home Mexico --away "South Africa" --competition worldcup --season 2026
+```
+
+Detailed JSON feeds can expose richer scoreboards and player history:
+
+```bash
+openmatch scoreboards --data-file tests/fixtures/sample_detailed_source.json
+openmatch scoreboard --match-id detail-1 --data-file tests/fixtures/sample_detailed_source.json
+openmatch live-scoreboards --data-file tests/fixtures/sample_detailed_source.json
+openmatch player-history --player "Alex Demo" --data-file tests/fixtures/sample_detailed_source.json
+```
+
+```python
+from openmatchkit import MatchClient
+from openmatchkit.sources.json_file import JsonFileSource
+
+client = MatchClient(sources=[JsonFileSource("tests/fixtures/sample_detailed_source.json")])
+scoreboard = client.scoreboard(match_id="detail-1")
+history = client.player_history("Alex Demo")
+print(scoreboard.model_dump(mode="json"))
+print(history.model_dump(mode="json"))
+```
+
+## Example Output
+
+```json
+{
+  "competition": "World Cup 2026",
+  "home": {"name": "Canada"},
+  "away": {"name": "Bosnia & Herzegovina"},
+  "status": "scheduled",
+  "source": "openfootball"
+}
+```
+
+## Features
+
+- Unified match, scoreboard, player history, standings, and prediction models
+- OpenFootball JSON adapter
+- Football-Data.co.uk CSV adapter
+- Local detailed JSON adapter for authorized/public detailed feeds
+- Generic optional public HTML adapter
+- Safe HTTP client with robots.txt checks, caching, user agent, and per-origin delay
+- Fixtures, results, next match, live score adapter interface, team info, standings
+- Detailed scoreboards: clock, events, lineups, team stats, and player match stats when provided
+- Player histories aggregated from player-level source data
+- Simple Poisson prediction baseline and small Elo rating helper
+- JSON and CSV export helpers
+- Offline tests using local fixtures
+
+## Current Status
+
+- Stable enough for demos, research, education, and early open-source feedback
+- Not official live FIFA data
+- True live/player-level data requires a lawful source adapter that provides those facts
+- Public roadmap: [ROADMAP.md](ROADMAP.md)
+- Release notes: [CHANGELOG.md](CHANGELOG.md)
+
+## Source and legal policy
+
+The package code is MIT licensed. Third-party data sources have their own licenses and terms. Optional scraping adapters must respect Terms of Service, robots.txt, caching, and rate limits. Player-level data should only come from public or authorized sources and should contain public sporting facts, not private or sensitive information.
+
+See [DATA_SOURCES.md](DATA_SOURCES.md), [PRIVACY.md](PRIVACY.md), and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format .
+pytest
+python -m build
+```
+
+The prediction output is an educational baseline only. It is not betting, financial, or professional advice.

openmatchkit-0.2.1/PRIVACY.md

@@ -0,0 +1,17 @@
+# Privacy
+
+openmatchkit is a local Python library. It does not include telemetry, analytics, tracking, accounts, cookies, or background data collection.
+
+Network requests happen only when user code or CLI commands call a source adapter that fetches public data. Those requests disclose normal HTTP metadata to the source, including IP address and User-Agent.
+
+Project rules:
+
+- Fetch public match facts only.
+- Do not collect personal data.
+- Do not process private accounts, login-only pages, or private APIs.
+- Do not store credentials in this package.
+- Do not bypass source protections or access controls.
+- Player data must be limited to public sporting facts from public or authorized sources, such as match appearances, goals, cards, and minutes played.
+- Do not collect contact information, private profiles, sensitive data, medical data, private social media data, or non-public information about players.
+
+If a community adapter needs credentials, it should live outside the default package or be clearly optional, documented, and disabled by default.