elecdef: a pure Python library of electrical blocks, pins, ratings and product identities for electrical engineers.
Site: https://olejbondahl.github.io/elecdef/
Index: https://olejbondahl.github.io/elecdef/
Guide: https://olejbondahl.github.io/elecdef/guide/
API: https://olejbondahl.github.io/elecdef/api/
Design: https://olejbondahl.github.io/elecdef/design/
Rules: https://olejbondahl.github.io/elecdef/rules/
Changelog: https://olejbondahl.github.io/elecdef/changelog/
Command: python -m elecdef api
Rule: a change follows RULES.md.
Names:
Unit: the units of every kind, each with an exact factor; calling a unit with a figure builds a Quantity.
Quantity: an exact Decimal figure with its unit; == compares as written, same and ordering use base units.
Range: a datasheet figure with a role, up to four ends and the At it holds under.
Ranges: a plain tuple of Range.
Role: what a stated figure means: RATED, LIMITING or REFERENCE.
At: the conditions a figure holds under, one per kind, in a canonical order.
pick: the one Range that covers every ask, or an Issue of NO_RATING or AMBIGUOUS_RATING.
Pick: the answer of pick, holding exactly one of found and issue.
Issue: one finding as a value: a code, a message and the subject it concerns.
IssueCode: the closed set of issue codes.
Symbol: a drawn symbol named by key and version; nothing else of it is held.
Product: a maker's part number, manufacturer, optional name and the one block it is.
check: the content issues of a block, or of a Product's block, as a tuple of Issue; it never raises for them.
Body: the outer shape of a thing: width, height, depth, protection code, temperatures and mounting.
Rating: voltages, currents per condition, thermal current, power loss, frequency, overvoltage category and pollution degree of a thing.
Connection: how a conductor attaches: technology, conductor ranges, strip length, torque, screw, pitch and material.
Contact: one contact: form, features, switching ratings and limiting voltage per condition, number and scheme; its pins and links are read from them.
Coil: a coil: kind, voltage, pick-up and drop-out, power, suppression; its A1 and A2 pins are read from kind and suppression.
Relay: a coil and contacts numbered 1..n on every read; the timer scheme when its kind is TIMER.
Contactor: a coil, MAKE main contacts numbered MAIN 1..n, then auxiliaries numbered AUX 1..n.
ContactBlock: a coil-less carrier of contacts numbered AUX from numbered_from.
PowerSupply: a power supply: its input, output figures and OK contact; the pins are read on every access.
PlcCard: a PLC card: supply, groups of channels, form, role, bus and safety levels; the pins are read on every access.
Device: a thing with no block of its own yet: its pins and links are stored as given.
Overload: a motor overload relay: main pins per pole, then auxiliaries numbered OVERLOAD.
Fuse: a fuse: system, class, current, voltage and breaking capacity, and its two pins.
Breaker: a circuit breaker: current, trip curve and breaking capacities, pole pins, auxiliaries.
TerminalBlock: a terminal block: its levels, the connection on each side and its mounting.
elecdef.vocab.Kind: the physical kind a unit belongs to; conversion and ordering stay inside one kind.
elecdef.vocab.Current: the current kind a figure is stated for, AC or DC.
elecdef.vocab.Utilisation: the utilisation code a contact rating is stated for, such as AC_15.
elecdef.vocab.CoilState: the state of a coil a figure is stated for, while pulling in or once held.
elecdef.vocab.ConductorKind: the construction of a conductor a terminal range is stated for.
elecdef.vocab.ActuatorKind: the kind of operating head.
elecdef.vocab.Armour: the armour construction.
elecdef.vocab.Bus: the field or network bus.
elecdef.vocab.CardForm: the build form of a card.
elecdef.vocab.CardRole: the role of a card in a station.
elecdef.vocab.CircuitClass: the protective class of a circuit.
elecdef.vocab.Coding: the connector coding key.
elecdef.vocab.CoilKind: the drive kind of a coil.
elecdef.vocab.Colour: a conductor colour code.
elecdef.vocab.ConductorClass: the conductor stranding class.
elecdef.vocab.ConductorMaterial: the metal a conductor is made of.
elecdef.vocab.ConnectorFamily: the connector family.
elecdef.vocab.ContactFeature: a special property of a contact.
elecdef.vocab.ContactForm: the switching form of a contact.
elecdef.vocab.ContactMaterial: the contact surface material.
elecdef.vocab.CoreRole: the role of a core in a cable.
elecdef.vocab.DiType: the digital input type.
elecdef.vocab.FuseClass: the fuse operating class, as typed on the fuse.
elecdef.vocab.FuseSpeed: the fuse speed letters.
elecdef.vocab.FuseSystem: the fuse construction system.
elecdef.vocab.Gender: the connector gender.
elecdef.vocab.Insulation: the conductor insulation material.
elecdef.vocab.IpCode: ingress protection class, by name.
elecdef.vocab.LevelKind: the kind of a terminal level.
elecdef.vocab.Locking: how a connector locks.
elecdef.vocab.Mounting: how a part is fixed in place.
elecdef.vocab.OutputKind: the digital output stage.
elecdef.vocab.OverloadBehaviour: how a supply behaves on overload.
elecdef.vocab.OvervoltageCategory: overvoltage category of the installation point.
elecdef.vocab.Pl: the performance level.
elecdef.vocab.Polarity: the digital channel polarity.
elecdef.vocab.PollutionDegree: pollution degree of the environment.
elecdef.vocab.PortKind: the kind of a data port.
elecdef.vocab.Potential: the potential a level carries.
elecdef.vocab.PsuKind: the kind of power supply.
elecdef.vocab.Rail: the mounting rail kind.
elecdef.vocab.RelayKind: the kind of relay.
elecdef.vocab.Reset: how a protective device is reset.
elecdef.vocab.RtdType: the resistance thermometer type.
elecdef.vocab.Scheme: the wire colour scheme family.
elecdef.vocab.Screen: the screen construction.
elecdef.vocab.ScrewSize: terminal screw thread size.
elecdef.vocab.SheathMaterial: the outer sheath material.
elecdef.vocab.Signal: the signal kind of a channel.
elecdef.vocab.Sil: the safety integrity level.
elecdef.vocab.Suppression: how a coil is suppressed against switch-off spikes.
elecdef.vocab.Technology: how a conductor or part is joined.
elecdef.vocab.ThermocoupleType: the thermocouple type letter.
elecdef.vocab.TimerFunction: the function of a timing relay.
elecdef.vocab.TripClass: the motor protection trip class.
elecdef.vocab.TripCurve: the breaker trip curve letter.
elecdef.connections.BOLT: the bolt connection leaf: technology only, every range unfilled.
elecdef.connections.CRIMP: the crimp connection leaf: technology only, every range unfilled.
elecdef.connections.IDC: the idc connection leaf: technology only, every range unfilled.
elecdef.connections.PLUG_IN: the plug in connection leaf: technology only, every range unfilled.
elecdef.connections.PRESS_IN: the press in connection leaf: technology only, every range unfilled.
elecdef.connections.PUSH_IN: the push in connection leaf: technology only, every range unfilled.
elecdef.connections.SCREW: the screw connection leaf: technology only, every range unfilled.
elecdef.connections.SMD: the smd connection leaf: technology only, every range unfilled.
elecdef.connections.SOLDER: the solder connection leaf: technology only, every range unfilled.
elecdef.connections.SPRING_CAGE: the spring cage connection leaf: technology only, every range unfilled.
elecdef.connections.TENSION: the tension connection leaf: technology only, every range unfilled.
elecdef.connections.THT: the tht connection leaf: technology only, every range unfilled.
elecdef.connections.WIRE_WRAP: the wire wrap connection leaf: technology only, every range unfilled.
elecdef.pins.Link: a join between two pins named by their markings, with its kind and whether it is closed at rest.
elecdef.pins.LinkKind: how two pins are joined: conductive, switched or protective.
elecdef.pins.Marking: the marking schemes: auxiliary, main, overload, timer and plain.
elecdef.pins.Pin: one pin: its marking, role, side and alternate markings.
elecdef.pins.PinRole: what a pin does in its part.
elecdef.pins.Side: which side of a part a pin is on.
elecdef.pins.contact_pins: the pins and links of contact n in a form under a marking scheme.
elecdef.supply.SupplyInput: what a powered thing draws: voltage and current per conditions, and its supply pins.
elecdef.plc.AnalogIo: an analog channel: a voltage or current span, resolution, wires, sensor type and accuracy.
elecdef.plc.Channel: one channel: its signal, number, electrical block and the pins it is wired on.
elecdef.plc.ChannelGroup: channels that share a template and a common: one per marking, numbered from first.
elecdef.plc.DigitalInput: what a digital input channel accepts: its type, polarity, voltage, thresholds and filter.
elecdef.plc.DigitalOutput: what a digital output channel delivers: its stage, polarity and current.
elecdef.terminal.Level: one level of a terminal: its marking, the potential it carries and its kind.
elecdef.fuse.FuseHolder: a fuse holder: pins 2p-1 and 2p per pole, each pole joined by a protective link.
elecdef.connector.Connector: a connector: family, coding, poles, gender, locking and whether it is shielded.
elecdef.computer.Computer: a computer: the supply it draws, its power and its data ports.
elecdef.computer.Port: a data port: its kind, how many there are and the connector it takes, if stated.
elecdef.conductor.Conductor: one conductor: material, class, cross-section, gauge, insulation, temperature and colour.
elecdef.cable.Cable: a cable: conductor, cores, screen, sheath and ratings; its pins are one per core plus SH.
elecdef.cable.Core: one core of a cable: number, colour, pair, role and own conductor.
elecdef.cable.TypeCode: a cable type designation: the scheme family and the text as printed.
elecdef.tables.AWG: American wire gauge rows (n, diameter, area), n from -3 (4/0) to 40.
elecdef.tables.AWG_METRIC: each gauge with the smallest cross section in CROSS_SECTIONS that holds its area.
elecdef.tables.BREAKER_CURRENTS: breaker rated currents in amperes.
elecdef.tables.BREAKER_CURVES: each trip curve with its low and high bound as multiples of rated current.
elecdef.tables.BREAKER_ICN: breaker rated breaking capacities in kiloamperes.
elecdef.tables.CABLE_VOLTAGES: cable voltage digits with the rated voltage to earth and between conductors.
elecdef.tables.CORE_COLOURS: core colours for positions 1 to 44, base colour first.
elecdef.tables.CROSS_SECTIONS: conductor cross sections in mm2.
elecdef.tables.E_SERIES: preferred value series E3, E6, E12 and E24 as (series, mantissa times ten) pairs.
elecdef.tables.OVERVOLTAGE_IMPULSE: impulse withstand voltage per overvoltage category.
elecdef.tables.TRIP_TIMES: trip time band in seconds per trip class, at 7.2 times the setting.
Rules:
F1. The library declares no runtime dependency and imports only the standard library and itself; libraries of the family never import each other.
F2. Every value is a frozen dataclass or an enum; the library performs no file, network, clock or random access.
F3. Validation returns issues as values and never raises for content; only a malformed call (a wrong type, a wrong kind of argument, or a shape the library's RULES.md names as malformed) raises TypeError.
F4. A closed vocabulary is an enum or a typed constant, never a string.
F5. A fact has one home across the family: symdef draws, elecdef says what a thing is, refdef says what it is called, a consumer connects and lays out.
F6. A caller's convention (a padding, an ordering, a default, a project class) arrives as an argument or a value; no general function carries a caller's default.
F7. No paid standard is cited and no standard's wording is used; open sources are used only with the credit block in README.md.
F8. The public surface is the names in __all__ of the top level and of each door, read by python -m <library> api, and it changes only with the snapshot.
F9. Every surface name has a docstring and a runnable example on the docs site.
F10. Code stays lean: a function has at most 15 statements, complexity 8 and 12 branches, no def inside a def; a module has at most 300 code lines; a docstring is one summary line plus at most two lines of why.
F11. Versions are semantic and every surface change carries a changelog line.
F12. A pull request that edits DESIGN.md or RULES.md, or changes docs/api-snapshot.txt, or changes a shipped table under src/<library>/tables/, carries a Design-review: trailer naming an approved review.
F13. A consumer's missing need is met by a reviewed surface extension, never by a workaround in the consumer, a private import, a copy of the rule or a consumer-specific default in the library.
F14. The library is MIT licensed, and the licence covers its code and its shipped tables.
F15. One public spelling per task: a second way to build, read or print the same value is not added, and no operator is overloaded to build a value; arithmetic belongs only to the numeric value types the library's RULES.md names.
F16. An agent finds everything from one place: AGENTS.md in the repository and llms.txt at the docs site root name the docs site, the surface command (python -m <library> api), the guide, DESIGN.md and RULES.md, and say that a change follows RULES.md.
F17. The library stands alone: no file in the repository names an application that uses it.
E1. The F4 allowlist for elecdef, covering fields annotated str or tuple[str, ...], is marking, alternates, markings, common, mpn, manufacturer, name, key, text, message, subject.
E2. A measured figure is a Decimal inside a Quantity, a count is an int, a flag is a bool, a derived ratio (tolerance) is a Fraction, and float appears nowhere.
E3. A Unit is an enum member with one Kind and an exact factor; conversion and comparison refuse a second kind.
E4. Every quantity field of a block declares its kind, and a value of another kind is refused at construction.
E5. A Range is written as Range(Role.X, nom=, min=, max=, at=) with an optional typ; role is positional and required, tolerance is a derived property, and there is no second constructor or helper spelling.
E6. Current kind, frequency, utilisation code, coil state, conductor kind and ambient are conditions in At, never fields of a block; two conditions of one kind in an At is the malformed shape F3 names.
E7. pick returns one covering range or an issue; it never returns the first of several.
E8. The library answers which stated figure applies and never whether a figure is acceptable: the only surface callables that return a truth value are Quantity.same, Quantity ordering, Range.contains, Range.covers and At.covers.
E9. Blocks compose by typed fields; an application never subclasses a block, and there is one base class, Block, for the kind check only.
E10. A composite's pins and links are computed from its sub-blocks and stored nowhere else; a leaf's are stored once.
E11. Pin markings, their alternates and marking schemes are data in elecdef.pins; a Coil or Contact stores only the pins its author gives (own_pins, may be empty) and computes pins on every read from its kind, form and position, and a composite numbers its unnumbered contacts on every read, so replace never leaves a stale marking; a marking is a non-empty string of letters, digits and / + - . '.
E12. A Connection belongs to the pins a block owns itself: Coil, Contact, SupplyInput, ChannelGroup, Fuse, FuseHolder, Breaker, Overload, PowerSupply, Connector and Device have one connection field, TerminalBlock has sides, and every other block has neither.
E13. elecdef.connections ships technology-only leaves with every range unfilled; vendor figures (torque, strip length, conductor ranges) never ship.
E14. Data tables are generated Python modules whose rows carry no origin, and a row ships only when the generator's input file, which records each row's origin (an open source, a maker's datasheet or a measurement) and its confirmation status, marks it confirmed.
E15. Product(mpn, manufacturer, block, name) is the one identity envelope; the library holds no supplier, price, footprint, class letter or description field.
E16. check reports exactly the content issues the design names: an end below another, a repeated marking, a marking outside the character set, a link naming no pin, a figure a block kind needs and lacks, a class outside the catalogue; IssueCode has these six codes (END_ORDER, DUPLICATE_MARKING, BAD_MARKING, DANGLING_LINK, MISSING_FIGURE, UNKNOWN_CLASS) and the two that pick returns (NO_RATING, AMBIGUOUS_RATING), eight in all.
E17. A block names its symbol by Symbol(key, version) and holds nothing else of it.
E18. For F15, Quantity is the only numeric value type, and in v1 it defines comparison dunders only; no surface class defines an arithmetic or bitwise dunder.
E19. Coverage never falls below 95 % per module, and ty check passes.
