Public Member Functions
Path	index_path (self, str user, *, bool create=False)
list[dict]	load_index (self, str user)
dict\|None	find_record (self, str owner, str doc_id)
Path	featured_path (self)
dict\|None	read_featured (self)
None	write_featured (self, dict\|None data)
Path	star_path (self)
Iterator[None]	star_lock (self)
list[dict]	read_star_raw (self)
set[tuple[str, str]]	read_star (self)
None	write_star (self, list[dict] entries)
str\|None	lock_holder (self, dict record)
None	require_lock_on (self, dict record, str doc_id, str viewer)
None	save_index (self, str user, list[dict] index)
Iterator[None]	index_lock (self, str user)
None	claim_for_write (self, str owner, str doc_id, str viewer)

Static Public Attributes
type	body_model [BaseModel]
type	create_model [BaseModel]
type	release_model [BaseModel]
Callable	to_data [[BaseModel], dict]
Callable	release_body [[BaseModel], dict \| None]
str	noun = "design"
str	default_slug = "design"
int	micro_interval = 300
int	lock_ttl = 900
Callable	empty_payload = lambda: {"config": {}}
bool	open_to_all = False
int	recent_days = None
bool	featured = False
bool	main_admin_only = True
bool	curated = False
False	is_admin = lambda request
dict	last_micro = field(default_factory=dict)

Detailed Description

One app's binding of the shared design machinery.

``empty_payload`` and ``payload_of`` are what let one router serve both the
``{"config": ...}`` apps and pid-designer's ``{"nodes": ..., "edges": ...}``:
everything else here treats a payload as an opaque JSON dict.

Definition at line 143 of file documents.py.

Member Function Documentation

◆ claim_for_write()

None stardesign.documents.DesignStore.claim_for_write	(		self,
		str	owner,
		str	doc_id,
		str	viewer )

Let ``viewer`` write the design's content, or 423.

Passes when ``viewer`` holds the checkout. Also passes -- and takes the
hold back -- when the hold lapsed *on* ``viewer`` and nobody has taken
the design since: a lapsed record keeps ``lockedBy``, any take by
someone else overwrites it, and a release clears it, so ``lockedBy ==
viewer`` on a free design means nobody else can have written it.

Refusing that case was how work was lost. Step away past ``lock_ttl``,
come back and keep editing, and every save came back 423 with nobody
else anywhere near the design; the edits stayed on screen and nowhere
else. A lapse still frees the design for anyone who acts first -- this
only stops the holder from being locked out of a design nobody wanted.

The check and the reclaim happen under the index lock, so a reclaim and
someone else's take serialise and exactly one of them wins.

Definition at line 381 of file documents.py.

References find_record(), index_lock(), load_index(), lock_holder(), require_lock_on(), and save_index().

◆ featured_path()

Path stardesign.documents.DesignStore.featured_path ( self )

Definition at line 232 of file documents.py.

Referenced by read_featured(), and write_featured().

◆ find_record()

dict \| None stardesign.documents.DesignStore.find_record	(		self,
		str	owner,
		str	doc_id )

Definition at line 229 of file documents.py.

References load_index().

Referenced by claim_for_write(), read_featured(), and read_star().

◆ index_lock()

Iterator[None] stardesign.documents.DesignStore.index_lock	(		self,
		str	user )

Serialize read-modify-write of one user's ``index.json``.

``save_index`` is atomic per write, but read-modify-write is not, and the
index is edited by co-editors as well as its owner while the API runs
several workers. Without this, two overlapping updates drop a record. The
lock file lives beside the index and is never removed.

Definition at line 364 of file documents.py.

Referenced by claim_for_write().

◆ index_path()

Path stardesign.documents.DesignStore.index_path	(		self,
		str	user,
		*	,
		bool	create = False )

Definition at line 213 of file documents.py.

Referenced by load_index(), and save_index().

◆ load_index()

list[dict] stardesign.documents.DesignStore.load_index	(		self,
		str	user )

One user's design records. Never creates their folder -- the
cross-user scan reads every sibling, and must not conjure a tree for
each one.

Definition at line 216 of file documents.py.

References index_path().

Referenced by claim_for_write(), and find_record().

◆ lock_holder()

str \| None stardesign.documents.DesignStore.lock_holder	(		self,
		dict	record )

Whoever currently holds the design, or None if it is free.

A checkout with no save inside ``lock_ttl`` is treated as free. Expiry is
decided here, on read, rather than by a background sweep -- which means
there is no window where a record says "held" and the answer to "may I
take it?" disagrees.

Definition at line 314 of file documents.py.

References lock_ttl.

Referenced by claim_for_write(), and require_lock_on().

◆ read_featured()

dict | None stardesign.documents.DesignStore.read_featured ( self )

``{owner, id, setBy, setAt}`` for the main design, or None.

None as well when the mode is off, or the file names a design that no
longer exists -- a dangling pointer must not make anything read-only.

Definition at line 235 of file documents.py.

References featured, featured_path(), and find_record().

Referenced by read_star().

◆ read_star()

set[tuple[str, str]] stardesign.documents.DesignStore.read_star ( self )

``(owner, id)`` of every STAR design, the main one included.

Entries naming a design that no longer exists are dropped, like a
dangling main pointer: they must not make anything visible.

Definition at line 293 of file documents.py.

References curated, find_record(), read_featured(), and read_star_raw().

◆ read_star_raw()

list[dict] stardesign.documents.DesignStore.read_star_raw ( self )

The STAR set as stored, dangling entries included.

Definition at line 281 of file documents.py.

References curated, and star_path().

Referenced by read_star().

◆ require_lock_on()

None stardesign.documents.DesignStore.require_lock_on	(		self,
		dict	record,
		str	doc_id,
		str	viewer )

Refuse a content write unless ``viewer`` holds this design's checkout.

The 423 and its wording are the contract the design bar reads: it drops
to read-only on 423 rather than retrying into a void.

Definition at line 334 of file documents.py.

References lock_holder().

Referenced by claim_for_write().

◆ save_index()

None stardesign.documents.DesignStore.save_index	(		self,
		str	user,
		list[dict]	index )

Write one user's index atomically (temp file + rename).

Definition at line 349 of file documents.py.

References index_path().

Referenced by claim_for_write().

◆ star_lock()

Iterator[None] stardesign.documents.DesignStore.star_lock ( self )

Serialise read-modify-write of the STAR set, as ``_index_lock`` does
for an index: two admins adding at once must not drop one.

Definition at line 269 of file documents.py.

◆ star_path()

Path stardesign.documents.DesignStore.star_path ( self )

Definition at line 265 of file documents.py.

Referenced by read_star_raw(), and write_star().

◆ write_featured()

None stardesign.documents.DesignStore.write_featured	(		self,
		dict \| None	data )

Set (or, with None, clear) the main design. Atomic, like the index.

Definition at line 254 of file documents.py.

References stardesign.documents._write_json_atomic(), and featured_path().

◆ write_star()

None stardesign.documents.DesignStore.write_star	(		self,
		list[dict]	entries )

Definition at line 311 of file documents.py.

References stardesign.documents._write_json_atomic(), and star_path().

Member Data Documentation

◆ body_model

type stardesign.documents.DesignStore.body_model [BaseModel]

static

Definition at line 156 of file documents.py.

◆ create_model

type stardesign.documents.DesignStore.create_model [BaseModel]

static

Definition at line 157 of file documents.py.

◆ curated

bool stardesign.documents.DesignStore.curated = False

static

Definition at line 195 of file documents.py.

Referenced by read_star(), and read_star_raw().

◆ default_slug

str stardesign.documents.DesignStore.default_slug = "design"

static

Definition at line 166 of file documents.py.

◆ empty_payload

Callable stardesign.documents.DesignStore.empty_payload = lambda: {"config": {}}

static

Definition at line 179 of file documents.py.

◆ featured

bool stardesign.documents.DesignStore.featured = False

static

Definition at line 186 of file documents.py.

Referenced by read_featured().

◆ is_admin

False stardesign.documents.DesignStore.is_admin = lambda request

static

Definition at line 197 of file documents.py.

◆ last_micro

dict stardesign.documents.DesignStore.last_micro = field(default_factory=dict)

static

Definition at line 203 of file documents.py.

◆ lock_ttl

int stardesign.documents.DesignStore.lock_ttl = 900

static

Definition at line 177 of file documents.py.

Referenced by lock_holder().

◆ main_admin_only

bool stardesign.documents.DesignStore.main_admin_only = True

static

Definition at line 189 of file documents.py.

◆ micro_interval

int stardesign.documents.DesignStore.micro_interval = 300

static

Definition at line 167 of file documents.py.

◆ noun

str stardesign.documents.DesignStore.noun = "design"

static

Definition at line 165 of file documents.py.

◆ open_to_all

bool stardesign.documents.DesignStore.open_to_all = False

static

Definition at line 181 of file documents.py.

◆ recent_days

int stardesign.documents.DesignStore.recent_days = None

static

Definition at line 184 of file documents.py.

◆ release_body

Callable stardesign.documents.DesignStore.release_body [[BaseModel], dict | None]

static

Definition at line 163 of file documents.py.

◆ release_model

type stardesign.documents.DesignStore.release_model [BaseModel]

static

Definition at line 158 of file documents.py.

◆ to_data

Callable stardesign.documents.DesignStore.to_data [[BaseModel], dict]

static

Definition at line 160 of file documents.py.

The documentation for this class was generated from the following file:

lib/stardesign/stardesign/documents.py

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ claim_for_write()

◆ featured_path()

◆ find_record()

◆ index_lock()

◆ index_path()

◆ load_index()

◆ lock_holder()

◆ read_featured()

◆ read_star()

◆ read_star_raw()

◆ require_lock_on()

◆ save_index()

◆ star_lock()

◆ star_path()

◆ write_featured()

◆ write_star()

Member Data Documentation

◆ body_model

◆ create_model

◆ curated

◆ default_slug

◆ empty_payload

◆ featured

◆ is_admin

◆ last_micro

◆ lock_ttl

◆ main_admin_only

◆ micro_interval

◆ noun

◆ open_to_all

◆ recent_days

◆ release_body

◆ release_model

◆ to_data