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.

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_.

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

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.

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:

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