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

python -m pip install bytewyrm

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

Connect to a Project

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

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 names, scores, levels, times and booleans. Your teacher chooses which fields the Store accepts and what rules they follow.

Save a record

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

A normal dictionary works too:

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

The returned record behaves like a normal Python dictionary:

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

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

Read records

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:

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

Sort records

For example, get the ten highest scores:

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

Or get the fastest times first:

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.

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

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

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

Sorting and filtering can be combined:

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

Read the newest record

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:

print(wyrm.store.schema())

Record information

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

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

print(wyrm.info())

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

Helpful printing

print(wyrm)

prints a short description instead of exposing the API key:

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

Likewise:

print(wyrm.store)

prints:

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:

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.

---

Teacher / advanced notes

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

wyrm = ByteWyrm(KEY)

Tools live beneath it:

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:

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:

python -m pip install -e .

Run the test suite:

python -m unittest discover -s tests -v