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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.