naming module#
File naming strategies and the registry behind –names.
Nothing else in this package builds a filename. Naming is a strategy object selected by name, and a strategy may return None for a file it has no opinion about, in which case the caller falls back to descriptive.
This library is fab-house agnostic and ships exactly one scheme, descriptive, which is self-explanatory rather than conventional. Legacy per-extension conventions and anything else a particular house asks for are house policy: they belong in that house’s library and register through the jitxlib.gerber.naming entry-point group, where they appear under –names with nothing to patch here.
- ENTRY_POINT_GROUP = 'jitxlib.gerber.naming'#
Entry-point group an out-of-tree scheme registers itself in.
- DEFAULT = 'descriptive'#
The scheme every other one falls back to. It must be total.
- DRILL_EXT: dict[DrillFormat, str] = {DrillFormat.GERBER: '.gbr', DrillFormat.XNC: '.xnc'}#
The extension each drill format is written under.
A drill file’s extension follows the format it is written in rather than being fixed, which is why Drill carries the format at all: a naming scheme branches on data it already has instead of on a string it would have to parse.
- exception NamingError[source]#
Bases:
LookupErrorNo such naming scheme.
- class FileNaming(*args, **kwargs)[source]#
Bases:
ProtocolA strategy that turns a file function into a filename.
Implement name and register the class under a scheme name. A scheme is free to return None for any file it has no convention for; the caller falls back to descriptive rather than inventing a name.
- name(function, stem, file_set)[source]#
The complete filename for one file, or None to defer.
- Parameters:
function (Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job) – what the file is, as the structured description it already carries for its TF.FileFunction attribute, so a scheme branches on data rather than on a rendered string.
stem (
str) – the scrubbed design name. Conventions that replace the extension entirely need it, which is why the strategy returns a whole filename rather than a suffix.file_set (
Sequence[Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job]) – every file function in the set being written, in emission order. Real conventions are not per-file functions of one file - whether a drill name needs decorating depends on whether the other drill file exists - so the set is passed even though many schemes will ignore it.
- Return type:
- register(scheme)[source]#
Register a naming strategy class under a scheme name.
Mirrors how the export plugin itself registers. The class is instantiated with no arguments at registration.
- strategy(scheme)[source]#
Resolve a scheme name to its strategy, or pass a strategy through.
Accepting an object as well as a name is what lets a caller hand over a configured instance without a registry round trip; the CLI only ever passes a name.
- Raises:
NamingError – no scheme is registered under that name.
- Return type:
- Parameters:
scheme (str | FileNaming)
- legal_stem(name)[source]#
Scrub a design name into a filename stem.
Restricted to ASCII on purpose, and as a portability rule rather than a fab-specific one: upload forms and older CAM tooling are known to reject filenames they cannot read as plain English, so a design name with non-ASCII characters must not be able to reach one.
The dot goes with them, for the same reason rather than a cosmetic one. A design name is a dotted module path in practice, so keeping dots would put several of them in every filename, and an upload form that reads the extension off the first dot rather than the last then sees a file it has no idea what to do with.
- resolve(functions, stem, scheme='descriptive')[source]#
Resolve a whole file set to filenames, parallel to functions.
A scheme that returns None for a file defers to descriptive, which is why descriptive must be total. Collision checking is deliberately not here: it belongs to the writer, which sees the archive name as well and is where a collision has to stop the run.
- Return type:
- Parameters:
functions (Sequence[FileFunction])
stem (str)
scheme (str | FileNaming)