Metadata-Version: 2.4
Name: sparecores-data
Version: 0.5.0
Summary: Structured data on cloud servers collected by sparecores-crawler.
Author: Gergely Daroczi, Attila Nagy
Maintainer-email: Spare Cores team <pkg@sparecores.com>
Project-URL: repository, https://github.com/SpareCores/sc-data
Project-URL: issues, https://github.com/SpareCores/sc-data/issues
Project-URL: homepage, https://sparecores.com
Keywords: cloud,compute,etl,sqlite,spot-instances,cost-optimization
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: sqlalchemy; extra == "dev"
Provides-Extra: all
Requires-Dist: sparecores-data[dev]; extra == "all"
Dynamic: license-file

## Spare Cores Navigator Data

[![Build](https://img.shields.io/github/actions/workflow/status/SpareCores/sc-data/tests.yaml)](https://github.com/SpareCores/sc-data/actions/workflows/tests.yaml)
[![Last data pull](https://img.shields.io/github/actions/workflow/status/SpareCores/sc-data-dumps/crawl.yaml?logo=sqlite&label=Last%20data%20pull)](https://github.com/SpareCores/sc-data-dumps/actions/workflows/crawl.yaml)
<picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/status-beta-blue"><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/status-beta-blue"><img alt="Project Status: Beta" src="https://img.shields.io/badge/status-beta-blue"></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/maintenance/yes/2026"><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/maintenance/yes/2026"><img alt="Maintenance Status: Active" src="https://img.shields.io/maintenance/yes/2026"></picture>
[![MPL 2.0 License](https://img.shields.io/github/license/SpareCores/sc-data)](https://github.com/SpareCores/sc-data/blob/main/LICENSE)
[![PyPI - Python Version](https://img.shields.io/pypi/v/sparecores-data?logo=python&logoColor=ffdd54)](https://pypi.org/project/sparecores-data/)
[![NGI Search Open Call 3 beneficiary](https://img.shields.io/badge/NGI%20Search-Open%20Call%20%233-blue?logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAyMi4xLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHdpZHRoPSIxODBweCIgaGVpZ2h0PSIxODBweCIgdmlld0JveD0iMCAwIDE4MCAxODAiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDE4MCAxODA7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4NCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI+DQoJLnN0MHtjbGlwLXBhdGg6dXJsKCNTVkdJRF8yXyk7fQ0KCS5zdDF7Y2xpcC1wYXRoOnVybCgjU1ZHSURfNF8pO2ZpbGw6dXJsKCNTVkdJRF81Xyk7fQ0KCS5zdDJ7ZmlsbDp1cmwoI1NWR0lEXzZfKTt9DQoJLnN0M3tmaWxsOiNGRkZGRkY7fQ0KPC9zdHlsZT4NCjxnPg0KCTxnPg0KCQk8ZGVmcz4NCgkJCTxwYXRoIGlkPSJTVkdJRF8xXyIgZD0iTTkwLDVDNDMuMiw1LDUsNDMuMiw1LDkwdjBjMCw0Ni43LDM4LjIsODUsODUsODVoMGM0Ni43LDAsODUtMzguMiw4NS04NXYwQzE3NSw0My4yLDEzNi44LDUsOTAsNUw5MCw1eiINCgkJCQkvPg0KCQk8L2RlZnM+DQoJCTxjbGlwUGF0aCBpZD0iU1ZHSURfMl8iPg0KCQkJPHVzZSB4bGluazpocmVmPSIjU1ZHSURfMV8iICBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZTsiLz4NCgkJPC9jbGlwUGF0aD4NCgkJPGcgY2xhc3M9InN0MCI+DQoJCQk8Zz4NCgkJCQk8ZGVmcz4NCgkJCQkJPHJlY3QgaWQ9IlNWR0lEXzNfIiB3aWR0aD0iMTgwIiBoZWlnaHQ9IjE4MCIvPg0KCQkJCTwvZGVmcz4NCgkJCQk8Y2xpcFBhdGggaWQ9IlNWR0lEXzRfIj4NCgkJCQkJPHVzZSB4bGluazpocmVmPSIjU1ZHSURfM18iICBzdHlsZT0ib3ZlcmZsb3c6dmlzaWJsZTsiLz4NCgkJCQk8L2NsaXBQYXRoPg0KCQkJCQ0KCQkJCQk8bGluZWFyR3JhZGllbnQgaWQ9IlNWR0lEXzVfIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9Ii0zMjQuNTY0MyIgeTE9IjIxMi4yNTg1IiB4Mj0iLTMyMy4zOTAzIiB5Mj0iMjEyLjI1ODUiIGdyYWRpZW50VHJhbnNmb3JtPSJtYXRyaXgoLTE1NS40ODE5IDE1MS4wOTY2IC0xNTEuMDk2NiAtMTU1LjQ4MTkgLTE4MjExLjA1ODYgODIwNDQuMjI2NikiPg0KCQkJCQk8c3RvcCAgb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojRTUzNTAwIi8+DQoJCQkJCTxzdG9wICBvZmZzZXQ9IjEiIHN0eWxlPSJzdG9wLWNvbG9yOiM1MDAwMkQiLz4NCgkJCQk8L2xpbmVhckdyYWRpZW50Pg0KCQkJCTxwb2x5Z29uIGNsYXNzPSJzdDEiIHBvaW50cz0iMjcwLDkyLjYgODcuNCwyNzAgLTkwLDg3LjQgOTIuNiwtOTAgCQkJCSIvPg0KCQkJPC9nPg0KCQk8L2c+DQoJCTxnIGNsYXNzPSJzdDAiPg0KCQkJDQoJCQkJPGxpbmVhckdyYWRpZW50IGlkPSJTVkdJRF82XyIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiIHgxPSItMzM3Ljg2MDYiIHkxPSIxOTguNzY1NSIgeDI9Ii0zMzguMzY1MiIgeTI9IjE5OC43NzI3IiBncmFkaWVudFRyYW5zZm9ybT0ibWF0cml4KC0xMjEuNzc5NCAxMTguMzQ0NiAtMTE4LjM0NDYgLTEyMS43Nzk0IC0xNzU2MS45Mzc1IDY0MzA5LjgxMjUpIj4NCgkJCQk8c3RvcCAgb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojNTAwMDJEIi8+DQoJCQkJPHN0b3AgIG9mZnNldD0iMSIgc3R5bGU9InN0b3AtY29sb3I6I0U1MzUwMCIvPg0KCQkJPC9saW5lYXJHcmFkaWVudD4NCgkJCTxwYXRoIGNsYXNzPSJzdDIiIGQ9Ik0xMDUuNiw4OC4yVjYzLjhjMC00LjMsMy41LTcuOCw3LjgtNy44aDBjNC4zLDAsNy44LDMuNSw3LjgsNy44djUyLjRjMCw0LjMtMy41LDcuOC03LjgsNy44aC0xLjUNCgkJCQljLTIuMywwLTQuNS0xLTYtMi44TDgwLjEsODkuN2MtMS45LTIuMy01LjctMS01LjcsMnYyNC41YzAsNC4zLTMuNSw3LjgtNy44LDcuOHMtNy44LTMuNS03LjgtNy44VjYzLjhjMC00LjMsMy41LTcuOCw3LjgtNy44DQoJCQkJaDEuNmMyLjMsMCw0LjUsMSw2LDIuOGwyNS43LDMxLjRDMTAxLjgsOTIuNiwxMDUuNiw5MS4zLDEwNS42LDg4LjJ6Ii8+DQoJCQk8cGF0aCBjbGFzcz0ic3QzIiBkPSJNNjguMiw1NmgtMS42Yy00LjMsMC03LjgsMy41LTcuOCw3Ljh2NTIuNGMwLDQuMywzLjUsNy44LDcuOCw3LjhzNy44LTMuNSw3LjgtNy44VjkxLjdjMC0zLDMuOC00LjQsNS43LTINCgkJCQlsMjUuOCwzMS41YzEuNSwxLjgsMy43LDIuOCw2LDIuOGgxLjVjNC4zLDAsNy44LTMuNSw3LjgtNy44VjYzLjhjMC00LjMtMy41LTcuOC03LjgtNy44aDBjLTQuMywwLTcuOCwzLjUtNy44LDcuOHYyNC41DQoJCQkJYzAsMy0zLjgsNC40LTUuNywyTDc0LjIsNTguOUM3Mi43LDU3LjEsNzAuNSw1Niw2OC4yLDU2eiIvPg0KCQk8L2c+DQoJPC9nPg0KPC9nPg0KPC9zdmc+DQo=)](https://www.ngisearch.eu/view/Events/OC3Searchers)

The Spare Cores Navigator Data is a Python package to make it easy to access the
latest version of the Spare Cores Navigator data via a SQLite database file.
This database file is compiled from an automatically downloaded, compressed
SQLite database dump, periodically updated by a background thread.

## Installation

Stable version from PyPI:

```
pip install sparecores-data
```

Most recent version from GitHub:

```
pip install "sparecores-data @ git+https://git@github.com/SpareCores/sc-data.git"
```

## Usage

For easy access to the most recent version of the SQLite database file, import
the `db` object of the `sc_data` Python package, which runs an updater thread
in the background to keep the SQLite file up-to-date:

```py
from sc_data import db
print(db.path)
```

The database is cached locally in a persistent directory and automatically
updated when needed. On import, the package:

1. Checks the local cache for a valid (non-stale) database
2. If cached and fresh, uses it immediately
3. Otherwise, downloads the latest version from our CDN

The cache is stored in a platform-specific location:
- **Linux**: `$XDG_CACHE_HOME/sparecores-data/` or `~/.cache/sparecores-data/`
- **macOS**: `~/Library/Caches/sparecores-data/`
- **Windows**: `%LOCALAPPDATA%/sparecores-data/`

To enforce waiting for the update to complete, you can use the `updated` event:

```py
db.updated.wait()
```

## Configuration

The package comes with the following set of default parameters, which can be
overridden by builtins or environment variables:

| Configuration | Description | Default Value | Builtin Name | Environment Variable |
|---------------|-------------|---------------|--------------|---------------------|
| Custom Database Path | Custom file path for the database (bypasses cache) | - | `sc_data_db_path` | `SC_DATA_DB_PATH` |
| Disable Updates | Whether to disable automatic updates | `False` | `sc_data_no_update` | `SC_DATA_NO_UPDATE` |
| Database URL | The URL of the most recent version of the database file (when unset, the default URL is used) | `https://cdn.sparecores.net/sc-data/sc-data-all.sql.xz` | `sc_data_db_url` | `SC_DATA_DB_URL` |
| HTTP Timeout | The timeout in seconds for downloading the database file | `30` | `sc_data_http_timeout` | `SC_DATA_HTTP_TIMEOUT` |
| Refresh Interval | The interval in seconds to check for database updates | `600` | `sc_data_db_refresh_seconds` | `SC_DATA_DB_REFRESH_SECONDS` |
| Suppress Data License Notice | Suppress the data license notice printed to stderr | - | `sc_data_no_license_notice` | `SC_DATA_NO_LICENSE_NOTICE` |

**Note**: Setting `SC_DATA_DB_PATH` disables caching and uses the specified file directly.

### Licensing

The source code of the `sparecores-data` package is released under the
[MPL 2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.

The default SQLite database dump file downloaded at runtime is published under the
[Business Source License 1.1 (BSL 1.1)](https://sparecores.com/legal/license-bsl) license.

Details -- including the publisher, timestamped release date, license type,
additional usage terms, and a link to the full license text -- is available in
the `_metadata` table of the database, and printed to the `stderr` by default
on every `Data` instantialization.

## References

- [Data source](https://github.com/SpareCores/sc-data-dumps)
- [sparecores.com](https://sparecores.com)
