Resource store¶
Look up a document’s resource files by identifier or filename.
ResourceStore¶
-
class creator_studio_doc_format.core.ResourceStore(initial=
None)[source]¶ Bases:
MutableMapping[str,bytes]The package’s resources, as a map from filename to bytes.
Saving writes exactly these entries to
Data/. A resource that the JSON embeds, such as aBase64EncodedResource, is never in the store. Any method that adds a key raisesValueErrorunless the key is a flat filename: nonempty, not.or.., and without/or\.A store from
Package.open_lazyknows every name up front but reads each resource from the archive on first access, solen, iteration, andinread nothing. Reading isn’t safe across threads.- Parameters:
- initial : Mapping[str, bytes] | None¶
The resources to start with, as a map from filename to bytes.
Keys match exactly, as in any mapping, so storing under a name that’s taken replaces that resource.
unique_filenamepicks a free name instead:>>> from creator_studio_doc_format.core import ResourceStore >>> store = ResourceStore({"logo.png": b"old"}) >>> name = store.unique_filename("logo.png") >>> store[name] = b"new" >>> sorted(store) ['logo 2.png', 'logo.png']The payload refers to a file from an
IndirectResource, by itsidentifieror, when that’s absent, itsfilename. That name’s spelling can differ from the key’s, such as a name that a zip tool stored decomposed. Indexing andinmiss it, andcan_resolveandbytes_forfind it:>>> import unicodedata >>> store = ResourceStore({unicodedata.normalize("NFD", "café.png"): b"png bytes"}) >>> "café.png" in store False >>> store.bytes_for("café.png") b'png bytes'- close()[source]¶
Releases the backing archive and keeps only the resources already read.
Calling
closeagain does nothing, and so does calling it on a store that isn’t lazy.
- bytes_for(identifier)[source]¶
Returns the bytes for an indirect resource’s identifier or filename.
Matching tries these in order:
The exact key.
A canonically equivalent key, so NFC and NFD spellings match.
The only key with the same ASCII characters as the identifier, which tolerates mojibake in zip names.
The ASCII match can return a different file:
é.pngresolves toè.pngwhen that’s the only key with the same ASCII characters. The resource check inPackage.saveaccepts the same match.- Parameters:
- identifier : str¶
An indirect resource’s
identifierorfilename.
- Returns:
The bytes of the first key that matches.
- Return type:
bytes- Raises:
KeyError– no key matches, or the ASCII match is ambiguous.DocumentPackageError– a lazy store reads a corrupt member.
- can_resolve(identifier)[source]¶
Returns a Boolean value that indicates whether a resource matches a name.
can_resolvematches names the waybytes_fordoes, and never reads bytes.- Parameters:
- identifier : str¶
An indirect resource’s
identifierorfilename.
- Returns:
Trueifbytes_forfinds a resource foridentifier, orFalseif it doesn’t.- Return type:
bool
- unique_filename(preferred)[source]¶
Returns a filename that no resource uses, based on a preferred name.
Reading and saving never rename a resource, so this is only for a caller adding one. The number goes before the last
., soa.tar.gzbecomesa.tar 2.gzand.hiddenbecomes" 2.hidden".- Parameters:
- preferred : str¶
The filename to use if no entry has it.
- Returns:
preferredif no entry has it, or else the first free numbered variant, such asname 2.ext.- Return type:
str
See also
Add an image, which shows how to name a file in the store.
Read resources only when you need them for opening a document without loading its resources.