Skip to main content

fuckyeah

Python client for the FuckYeah API. It controls your devices and manages patterns from scripts and projects.

The client speaks API v2 (https://api.fuckyeah.uk/v2). Create a FuckYeahClient with a personal API token and the token is sent on every request as Authorization: Bearer fy_....

Install

pip install fuckyeah

Requires Python 3.10 or newer.

Authentication

Create a token in the app. Choose a name, the scopes it needs, and, optionally, when it expires. The token is shown once and starts with fy_.

import os

from fuckyeah import FuckYeahClient

with FuckYeahClient(os.environ["FUCKYEAH_TOKEN"]) as client:
    for device in client.list_devices():
        print(device.id, device.name)

FuckYeahClient checks that the token is shaped like a personal token. The API does not provide a way to inspect a token without calling a scoped endpoint, so a rejected, expired, or revoked token raises AuthenticationError on the first protected call.

Give each token only the scopes it needs.

Scope Allows
devices:read List and view devices.
devices:manage Add, rename, and remove devices.
devices:control Send commands and load patterns onto devices.
patterns:read List and view patterns.
patterns:write Create, update, and delete your patterns.

A request without the required scope returns HTTP 403.

Devices

device = client.register_device("Desk", pin=1234)
client.rename_device(device, "Window")

client.load_patterns(device, [pattern_id])
client.run_pattern(device, pattern_id=pattern_id, speed=0.5, r1="pattern", r2="off")
client.stop_device(device)

client.delete_device(device)

register_device claims a connected machine with the PIN on its screen. The PIN rotates, so register it soon after reading it.

run_pattern and stop_device return when the API accepts the command (HTTP 202). The device does not confirm that it applied the command. It has to be online, with remote control enabled. Speed and stroke values are fractions of the room left by the device's own settings and the active pattern phase. After a stop, the speed stays at 0 and both relays stay off until the next run_pattern sends new values.

Deleting a device detaches its patterns. The patterns remain available to your other devices, and the machine has to be registered again before it can be used online.

Patterns

from fuckyeah import Phase

pattern = client.create_pattern(
    "Pulse",
    [
        Phase(p=0.2, s=0.4, a=0.5, d=0.0, r1=False, r2=False),
        Phase(p=0.8, s=0.7, a=0.5, d=0.2, r1=True, r2=False),
    ],
    description="A short pulse",
    public=False,
)

for item in client.iter_patterns(types=["user", "default"], query="pulse"):
    print(item.id, item.name, item.type)

client.update_pattern(pattern, public=True)
client.delete_pattern(pattern)

A pattern name is ASCII and at most 19 characters so it fits on the device screen. A pattern has 2 to 150 phases. In a phase, p is position (0 to 1), s is speed (0.01 to 1), a is acceleration (0.01 to 1), d is delay in seconds (0 to 5), and r1 / r2 switch the auxiliary relays.

list_patterns returns one page of 20, ordered by name. Pass cursor=page.next_cursor to continue, or use iter_patterns to follow the cursors. types accepts user (yours), public, default, or a combination. query keeps names that contain that text.

type on a returned pattern is user, default, public, or a value added later. Unknown values are left as they arrived. author is set only when that person has a public profile.

Changing anything other than public creates a new pattern revision so a device can tell that it should reload. Pass description=None to clear a description. You can delete only your own patterns; copies other people made are left alone.

Tokens

client.revoke_token()

This calls DELETE /auth/token and then refuses further requests on this client. You can also revoke a token from the app.

Errors

Exception When
AuthenticationError HTTP 401. The token is missing, invalid, expired, or revoked.
AuthorizationError HTTP 403. The token lacks the scope, or the account email is not verified.
NotFoundError HTTP 404.
ValidationError HTTP 422. errors maps each field to the messages returned for it.
RateLimitError HTTP 429. retry_after is the Retry-After delay in seconds, when the API sent one.
TransportError The connection failed or timed out before a response arrived.
FuckYeahError Any other client or response failure. The exceptions above are subclasses of this.

HTTP 429 is retried up to max_retries times (default 2) when Retry-After is 60 seconds or less. A longer delay is raised immediately as RateLimitError so the caller can decide whether to wait. Pass max_retries=0 to disable retries.

client.rate_limit holds the x-ratelimit-limit and x-ratelimit-remaining values from the most recent response, when those headers were present.

Redirects are not followed, so the bearer token stays on the host in base_url.

Compatibility

Within /v2, the API only adds fields, endpoints, and enum values. This client ignores response fields it does not recognise. The published schema types min_app_versions as a string; the live API returns an object with ios and android. get_version() accepts both.

Breaking changes will arrive as a new API version. Point base_url at that version when you are ready to move.

Development

pip install -e ".[dev]"
pytest

The version in src/fuckyeah/_version.py is the version published to PyPI. Build and upload with your usual tools:

python -m build
twine upload dist/*

Support for the API itself is support@fuckyeah.uk.

Metadata

Release files for fuckyeah 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fuckyeah 0.1.0
File Size Uploaded Provenance Actions
fuckyeah-0.1.0.tar.gz 19.7 kB Without provenance Details for fuckyeah-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fuckyeah 0.1.0
File Interpreter ABI Platform Actions
fuckyeah-0.1.0-py3-none-any.whl Python 3 none any Details for fuckyeah-0.1.0-py3-none-any.whl

Total release size: 36.9 kB

Release files / fuckyeah-0.1.0.tar.gz

Download URL fuckyeah-0.1.0.tar.gz
Size 19.7 kB
Tags Source
SHA-256 checksum
How to use checksums
8c8b37e8529d995ae830bfbad1460902c5038945bd9af6d5fa3c07a1960cead2
BLAKE2b-256 checksum
How to use checksums
701f0a4d16052002886ab46f8b2f7340f77bf387174cc8f607c09ebb023462e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / fuckyeah-0.1.0-py3-none-any.whl

Download URL fuckyeah-0.1.0-py3-none-any.whl
Size 17.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b9ab4da25380bcaea4dafc1687c79d1e1260e05a7309a23c4860e86871b5275b
BLAKE2b-256 checksum
How to use checksums
a49324fe4a2bc463503feca71946faa7b29e699d848716a53b090068be09e94a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for fuckyeah 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page