Metadata-Version: 2.4
Name: bytewyrm
Version: 0.5.3
Summary: Beginner-friendly online tools for small Python game projects.
Author: ByteWyrm
License-Expression: MIT
Project-URL: Homepage, https://bytewyrm.dev
Project-URL: Repository, https://github.com/William-Nitrosis/bytewyrm
Project-URL: Issues, https://github.com/William-Nitrosis/bytewyrm/issues
Project-URL: API, https://api.bytewyrm.dev
Keywords: education,games,api,students,bytewyrm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ByteWyrm

ByteWyrm gives small Python game projects simple online tools without making students build or manage a server themselves.

The package is designed for learners: create one `ByteWyrm` object, then use the tools inside it. Networking, web requests, JSON, authentication headers and server details stay out of the way.

> ByteWyrm is currently an alpha project. The API is intentionally small and may grow as more tools are added.

## Install

```bash
python -m pip install bytewyrm
```

ByteWyrm requires Python 3.10 or newer and has no third-party runtime dependencies.

## Data safety

> **ByteWyrm is designed for small amounts of non-sensitive game data only.**

Good examples include scores, player nicknames, progress values, lap times, flags and other simple game state.

Do **not** use ByteWyrm to store real names, email addresses, passwords, addresses, private messages, medical information, or other personal, sensitive, or confidential information.

The Python library also prints a short safety notice the first time a `ByteWyrm` object is created in each program run. It is a normal console message rather than a Python warning, so Python does not echo the source line containing your API key.

## Connect to a Project

Your teacher will normally give you a ByteWyrm key beginning with `bwk_`.

```python
from bytewyrm import ByteWyrm


wyrm = ByteWyrm("bwk_YOUR_KEY_HERE")
```

You normally create this object once near the start of your program.

## Store

The Store saves small pieces of structured data such as player nicknames, scores, levels, times and booleans. Your teacher chooses which fields the Store accepts and what rules they follow.

### Save a record

```python
wyrm.store.add(
    player="Drake",
    score=12500,
)
```

A normal dictionary works too:

```python
wyrm.store.add({
    "player": "Drake",
    "score": 12500,
})
```

The returned record behaves like a normal Python dictionary:

```python
record = wyrm.store.add(player="Drake", score=12500)

print(record["player"])
print(record["score"])
```

### Read records

```python
records = wyrm.store.records()

for record in records:
    print(record["player"], record["score"])
```

With no extra options, the newest records are returned first.

Ask for fewer records with:

```python
records = wyrm.store.records(limit=10)
```

### Sort records

For example, get the ten highest scores:

```python
top_scores = wyrm.store.records(
    sort_by="score",
    reverse=True,
    limit=10,
)
```

Or get the fastest times first:

```python
fastest_times = wyrm.store.records(
    sort_by="time",
)
```

### Filter records

ByteWyrm intentionally keeps filtering simple. Use one of `equals`, `greater_than` or `less_than` at a time.

```python
finished = wyrm.store.records(
    where="completed",
    equals=True,
)
```

```python
high_scores = wyrm.store.records(
    where="score",
    greater_than=1000,
)
```

```python
fast_runs = wyrm.store.records(
    where="time",
    less_than=60,
)
```

Sorting and filtering can be combined:

```python
top_finished = wyrm.store.records(
    where="completed",
    equals=True,
    sort_by="score",
    reverse=True,
    limit=10,
)
```

### Read the newest record

```python
record = wyrm.store.latest()

if record is not None:
    print(record["score"])
```

If nothing has been saved yet, `latest()` returns `None`.

### See what the Store accepts

Your teacher will normally tell you which values the Store accepts, but you can inspect its schema:

```python
print(wyrm.store.schema())
```

## Record information

Store records behave like dictionaries, but ByteWyrm also keeps the record number and creation time:

```python
record = wyrm.store.latest()

if record is not None:
    print(record.id)
    print(record.created_at)
```

Most student projects will not need these extra values.

## Project information

```python
print(wyrm.info())
```

This shows information about the ByteWyrm Project connected to your key.

## Helpful printing

```python
print(wyrm)
```

prints a short description instead of exposing the API key:

```text
ByteWyrm Project (use .store to work with Store data)
```

Likewise:

```python
print(wyrm.store)
```

prints:

```text
ByteWyrm Store (use .add(), .records(), .latest(), or .schema())
```

## Errors

ByteWyrm turns connection and server problems into beginner-friendly Python errors.

If you know `try` and `except`, you can catch normal ByteWyrm problems using `ByteWyrmError`:

```python
from bytewyrm import ByteWyrm, ByteWyrmError


wyrm = ByteWyrm("bwk_YOUR_KEY_HERE")

try:
    wyrm.store.add(player="Drake", score=12500)
except ByteWyrmError as error:
    print(error)
```

More specific error classes are available for authentication, permissions, validation, rate limits, connection problems and server errors.

## Keep your key private

A ByteWyrm key gives a program permission to use part of a Project. Do not post a real key publicly or commit one to a public repository unless your teacher has told you it is safe to do so.

ByteWyrm deliberately masks the key in its normal `str()`/`repr()` output, safety notice, and error messages. The key still has to exist in your program's memory so requests can be authenticated, so code that deliberately inspects private attributes can still retrieve it.

---

## Teacher / advanced notes

The student-facing API is intentionally based around one object:

```python
wyrm = ByteWyrm(KEY)
```

Tools live beneath it:

```python
wyrm.store
```

The key identifies the Project, so normal student code does not need a Project ID, URL, HTTP headers or database details.

The client deliberately hides HTTP requests, bearer authentication, JSON encoding/decoding, pagination cursors and server status codes. It uses only the Python standard library at runtime.

The production API defaults to:

```text
https://api.bytewyrm.dev
```

A custom `base_url` and request `timeout` are available on `ByteWyrm(...)` for development/testing.

### Development

Install the package in editable mode:

```bash
python -m pip install -e .
```

Run the test suite:

```bash
python -m unittest discover -s tests -v
```
