elecdef 0.1.0__py3-none-any.whl

elecdef/__init__.py

@@ -0,0 +1,51 @@
+"""Standard-agnostic electrical engineering vocabulary as strict, typed, immutable values."""
+
+from elecdef._body import Body
+from elecdef._breaker import Breaker
+from elecdef._check import check
+from elecdef._coil import Coil
+from elecdef._connection import Connection
+from elecdef._contact import Contact
+from elecdef._device import Device
+from elecdef._issue import Issue, IssueCode
+from elecdef._overload import Overload
+from elecdef._plccard import PlcCard
+from elecdef._product import Product, Symbol
+from elecdef._psu import PowerSupply
+from elecdef._quantity import Quantity, Unit
+from elecdef._range import At, Pick, Range, Ranges, Role, pick
+from elecdef._rating import Rating
+from elecdef._relay import ContactBlock, Contactor, Relay
+from elecdef.fuse import Fuse
+from elecdef.terminal import TerminalBlock
+
+__all__ = [
+    "At",
+    "Body",
+    "Breaker",
+    "Coil",
+    "Connection",
+    "Contact",
+    "ContactBlock",
+    "Contactor",
+    "Device",
+    "Fuse",
+    "Issue",
+    "IssueCode",
+    "Overload",
+    "Pick",
+    "PlcCard",
+    "PowerSupply",
+    "Product",
+    "Quantity",
+    "Range",
+    "Ranges",
+    "Rating",
+    "Relay",
+    "Role",
+    "Symbol",
+    "TerminalBlock",
+    "Unit",
+    "check",
+    "pick",
+]

elecdef/__main__.py

@@ -0,0 +1,18 @@
+"""Command line: `python -m elecdef api` prints the public surface."""
+
+import sys
+
+from elecdef._api import DOORS, render
+
+
+def main(argv: list[str]) -> int:
+    """Run the one command, `api`; any other argument is a usage error (exit 2)."""
+    if argv != ["api"]:
+        sys.stderr.write("usage: python -m elecdef api\n")
+        return 2
+    sys.stdout.write(render(DOORS))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

elecdef/_api.py

@@ -0,0 +1,56 @@
+"""The surface printer: `render` lists every door's `__all__` with signatures and docstrings."""
+
+import annotationlib
+import dataclasses
+import enum
+import importlib
+import inspect
+
+DOORS: tuple[str, ...] = (
+    "elecdef",
+    "elecdef.vocab",
+    "elecdef.connections",
+    "elecdef.pins",
+    "elecdef.supply",
+    "elecdef.plc",
+    "elecdef.tables",
+    "elecdef.terminal",
+    "elecdef.fuse",
+    "elecdef.conductor",
+    "elecdef.cable",
+    "elecdef.connector",
+    "elecdef.computer",
+)
+
+
+def _signature(obj: object) -> str:
+    """The signature as source text, so 3.14 and 3.15 print the same bytes."""
+    return str(inspect.signature(obj, annotation_format=annotationlib.Format.STRING))  # ty: ignore[invalid-argument-type] - obj is callable here
+
+
+def _head(name: str, obj: object) -> str:
+    """The first line of a name's entry."""
+    if isinstance(obj, type) and issubclass(obj, enum.Enum):
+        return f"class {name}"
+    if isinstance(obj, type) and dataclasses.is_dataclass(obj):
+        return f"class {name}{_signature(obj)}"
+    if callable(obj):
+        return f"{name}{_signature(obj)}"
+    return f"{name}: {type(obj).__name__}"
+
+
+def _entry(name: str, obj: object) -> list[str]:
+    """A name's head, its docstring indented four spaces, and a blank line."""
+    doc = inspect.getdoc(obj if callable(obj) else type(obj)) or ""
+    return [_head(name, obj), *(f"    {line}".rstrip() for line in doc.splitlines()), ""]
+
+
+def render(doors: tuple[str, ...]) -> str:
+    """Return the public surface of `doors` as text: deterministic, one final newline."""
+    lines: list[str] = []
+    for door in doors:
+        module = importlib.import_module(door)
+        lines.append(f"## {door}")
+        for name in sorted(module.__all__):
+            lines += _entry(name, getattr(module, name))
+    return "\n".join(lines).rstrip("\n") + "\n"

elecdef/_block.py

@@ -0,0 +1,56 @@
+"""The one base class of the blocks: it checks the kind of each figure and wraps a bare Range."""
+
+from dataclasses import dataclass, field, fields
+from typing import Any, ClassVar
+
+from elecdef._quantity import Kind, Quantity
+from elecdef._range import Range
+
+__all__ = ["Block", "figure"]
+
+
+def figure(*kinds: Kind, many: bool = False) -> Any:  # noqa: ANN401 - dataclasses types field() as Any
+    """A block field that holds a figure of one of `kinds`; `many` holds a tuple of Range."""
+    return field(default=() if many else None, metadata={"kinds": kinds, "many": many})
+
+
+def _kind_of(value: object) -> Kind:
+    """The kind of a Quantity or a Range; any other value is a TypeError."""
+    if isinstance(value, Quantity):
+        return value.unit.kind
+    if isinstance(value, Range):
+        return value.kind
+    message = f"a figure is a Quantity or a Range, not {type(value).__name__}"
+    raise TypeError(message)
+
+
+def _check_figure(name: str, value: object, kinds: tuple[Kind, ...]) -> None:
+    """Refuse a filled figure whose kind is not one of `kinds`."""
+    if value is not None and _kind_of(value) not in kinds:
+        message = f"{name} takes {[kind.name for kind in kinds]}, not {_kind_of(value).name}"
+        raise TypeError(message)
+
+
+@dataclass(frozen=True)
+class Block:
+    """The base of every block: refuses a figure of another kind at construction."""
+
+    needs: ClassVar[tuple[str, ...]] = ()
+
+    def __post_init__(self) -> None:
+        """Check each filled figure and wrap a bare Range given to a `many` field."""
+        for item in fields(self):
+            if "kinds" not in item.metadata:
+                continue
+            value = getattr(self, item.name)
+            if not item.metadata["many"]:
+                _check_figure(item.name, value, item.metadata["kinds"])
+                continue
+            if isinstance(value, Range):
+                value = (value,)
+                object.__setattr__(self, item.name, value)
+            if not isinstance(value, tuple):
+                message = f"{item.name} is a tuple of Range"
+                raise TypeError(message)
+            for each in value:
+                _check_figure(item.name, each, item.metadata["kinds"])

elecdef/_body.py

@@ -0,0 +1,25 @@
+"""The Body block: the outer size, protection, temperature and mounting of a part."""
+
+from dataclasses import dataclass
+
+from elecdef._block import Block, figure
+from elecdef._quantity import Kind, Quantity
+from elecdef._range import Ranges
+from elecdef.vocab import IpCode, Mounting
+
+__all__ = ["Body"]
+
+
+@dataclass(frozen=True)
+class Body(Block):
+    """The physical body of a part.
+
+    Temperature rows tell operating (RATED) from storage (LIMITING) by their role.
+    """
+
+    width: Quantity | None = figure(Kind.LENGTH)
+    height: Quantity | None = figure(Kind.LENGTH)
+    depth: Quantity | None = figure(Kind.LENGTH)
+    ip: IpCode | None = None
+    temperature: Ranges = figure(Kind.TEMPERATURE, many=True)
+    mounting: Mounting | None = None

elecdef/_breaker.py

@@ -0,0 +1,62 @@
+"""The Breaker block: pole pins as a fuse holder has them, then auxiliaries numbered AUX."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from elecdef._block import Block, figure
+from elecdef._body import Body
+from elecdef._connection import Connection
+from elecdef._contact import Contact
+from elecdef._numbering import _joined, _numbered
+from elecdef._product import Symbol
+from elecdef._quantity import Kind
+from elecdef._range import Range
+from elecdef._rating import Rating
+from elecdef.fuse import pole_pins
+from elecdef.pins import Link, Marking, Pin
+from elecdef.vocab import TripCurve
+
+__all__ = ["Breaker"]
+
+
+@dataclass(frozen=True)
+class Breaker(Block):
+    """A circuit breaker: current, trip curve and breaking capacities, pole pins, auxiliaries.
+
+    Pins and links are computed on every read, so `replace(breaker, poles=1)` leaves none stale.
+    """
+
+    needs: ClassVar[tuple[str, ...]] = ("current", "curve")
+
+    poles: int | None = None
+    current: Range | None = figure(Kind.CURRENT)
+    curve: TripCurve | None = None
+    icn: Range | None = figure(Kind.CURRENT)
+    icu: Range | None = figure(Kind.CURRENT)
+    ics: Range | None = figure(Kind.CURRENT)
+    rating: Rating | None = None
+    aux: tuple[Contact, ...] = ()
+    connection: Connection | None = None
+    body: Body | None = None
+    symbol: Symbol | None = None
+
+    def __post_init__(self) -> None:
+        """Check the figures, then read the pins once so a bad pole count fails here."""
+        super().__post_init__()
+        _ = self.pins
+
+    def _joined(self) -> tuple[tuple[Pin, ...], tuple[Link, ...]]:
+        """The pole pins and links, then those of the auxiliaries."""
+        pole_p, pole_l = pole_pins(self.poles)
+        pins, links = _joined(None, _numbered(self.aux, Marking.AUX))
+        return pole_p + pins, pole_l + links
+
+    @property
+    def pins(self) -> tuple[Pin, ...]:
+        """The pole pins, then the pins of each auxiliary contact."""
+        return self._joined()[0]
+
+    @property
+    def links(self) -> tuple[Link, ...]:
+        """One protective link per pole, then the links of the auxiliaries."""
+        return self._joined()[1]

elecdef/_check.py

@@ -0,0 +1,62 @@
+"""`check`: the content issues of a block or a Product, reported as values and never raised."""
+
+from elecdef._block import Block
+from elecdef._checkpins import duplicate_issues, link_issues, marking_issues
+from elecdef._checkwalk import join, walk
+from elecdef._issue import Issue, IssueCode
+from elecdef._product import Product
+from elecdef._range import Range
+
+__all__ = ["check"]
+
+_ORDER = (("min", "nom"), ("min", "typ"), ("min", "max"), ("nom", "max"), ("typ", "max"))
+
+
+def _range_issues(path: str, item: Range) -> list[Issue]:
+    """END_ORDER for a Range whose ends are not in order."""
+    wrong = [
+        f"{low} is above {high}"
+        for low, high in _ORDER
+        if getattr(item, low) is not None
+        and getattr(item, high) is not None
+        and getattr(item, low) > getattr(item, high)
+    ]
+    return [Issue(IssueCode.END_ORDER, "; ".join(wrong), path)] if wrong else []
+
+
+def _block_issues(path: str, block: Block, *, product: bool) -> list[Issue]:
+    """UNKNOWN_CLASS, the marking and link issues, and MISSING_FIGURE inside a Product."""
+    found: list[Issue] = []
+    module = type(block).__module__
+    if module != "elecdef" and not module.startswith("elecdef."):
+        message = f"{type(block).__qualname__} is not defined in the elecdef catalogue"
+        found.append(Issue(IssueCode.UNKNOWN_CLASS, message, path or "block"))
+    found += marking_issues(path, block) + link_issues(path, block)
+    if product:
+        found.extend(
+            Issue(IssueCode.MISSING_FIGURE, f"{name} is needed and unfilled", join(path, name))
+            for name in type(block).needs
+            if getattr(block, name) in (None, ())
+        )
+    return found
+
+
+def check(block: Block | Product) -> tuple[Issue, ...]:
+    """Report the content issues of a block, or of the block inside a Product, as a tuple.
+
+    A figure a block kind needs is reported only inside a Product; a bare block is a template.
+    """
+    if isinstance(block, Product):
+        root, product = block.block, True
+    elif isinstance(block, Block):
+        root, product = block, False
+    else:
+        message = f"check takes a Block or a Product, not {type(block).__name__}"
+        raise TypeError(message)
+    found: list[Issue] = []
+    for path, item in walk(root):
+        if isinstance(item, Range):
+            found += _range_issues(path, item)
+        else:
+            found += _block_issues(path, item, product=product)
+    return tuple(found + duplicate_issues(root))

elecdef/_checkpins.py

@@ -0,0 +1,84 @@
+"""The pin issues of `check`: marking syntax once per authored pin, uniqueness over the device."""
+
+from dataclasses import fields
+
+from elecdef._block import Block
+from elecdef._checkwalk import join, walk
+from elecdef._issue import Issue, IssueCode
+from elecdef.pins import Pin, _is_marking
+
+
+def _pin_field(block: Block) -> str | None:
+    """The attribute that holds the pins the author gave, or a leaf's computed `pins`."""
+    names = {item.name for item in fields(block)}
+    if "own_pins" in names:
+        return "own_pins"
+    if "pins" in names:
+        return "pins"
+    leaf = all(item is block for _, item in walk(block) if isinstance(item, Block))
+    return "pins" if leaf and hasattr(block, "pins") else None
+
+
+def authored(path: str, block: Block) -> list[tuple[str, Pin]]:
+    """Each pin the block authors, with its subject path; a composite's computed pins are not."""
+    name = _pin_field(block)
+    if name is None:
+        return []
+    return [(f"{join(path, name)}[{index}]", pin) for index, pin in enumerate(getattr(block, name))]
+
+
+def marking_issues(path: str, block: Block) -> list[Issue]:
+    """BAD_MARKING for each authored pin whose marking is not a run of marking characters."""
+    return [
+        Issue(
+            IssueCode.BAD_MARKING,
+            f"pin marking {pin.marking!r} is not a run of marking characters",
+            subject,
+        )
+        for subject, pin in authored(path, block)
+        if not _is_marking(pin.marking)
+    ]
+
+
+def link_issues(path: str, block: Block) -> list[Issue]:
+    """DANGLING_LINK for each link marking that names no pin of the block."""
+    names = {pin.marking for pin in getattr(block, "pins", ())}
+    return [
+        Issue(
+            IssueCode.DANGLING_LINK,
+            f"link names {marking!r}, which is no pin",
+            f"{join(path, 'links')}[{index}]",
+        )
+        for index, link in enumerate(getattr(block, "links", ()))
+        for marking in link.markings
+        if marking not in names
+    ]
+
+
+def _subjects(root: Block, pins: tuple[Pin, ...]) -> list[str]:
+    """The subject of each pin in the root's full pin set: its authored path, else `pins[i]`."""
+    pool = [
+        pair
+        for path, item in walk(root)
+        if isinstance(item, Block)
+        for pair in authored(path, item)
+    ]
+    subjects: list[str] = []
+    for index, pin in enumerate(pins):
+        match = next((at for at, (_, given) in enumerate(pool) if given == pin), None)
+        subjects.append(pool.pop(match)[0] if match is not None else f"pins[{index}]")
+    return subjects
+
+
+def duplicate_issues(root: Block) -> list[Issue]:
+    """DUPLICATE_MARKING for each repeat after the first over the outermost block's full pins."""
+    pins = tuple(getattr(root, "pins", ()))
+    found: list[Issue] = []
+    seen: set[tuple[str, object]] = set()
+    for pin, subject in zip(pins, _subjects(root, pins), strict=True):
+        if (pin.marking, pin.side) in seen:
+            side = f" on side {pin.side.name}" if pin.side else ""
+            message = f"pin marking {pin.marking!r} is repeated{side}"
+            found.append(Issue(IssueCode.DUPLICATE_MARKING, message, subject))
+        seen.add((pin.marking, pin.side))
+    return found

elecdef/_checkwalk.py

@@ -0,0 +1,26 @@
+"""The generic walk `check` makes: every Block and Range under a value, with its path."""
+
+from collections.abc import Iterator
+from dataclasses import fields, is_dataclass
+
+from elecdef._block import Block
+from elecdef._range import Range
+
+
+def join(path: str, name: str) -> str:
+    """The path of `name` under `path`."""
+    return f"{path}.{name}" if path else name
+
+
+def walk(value: object, path: str = "") -> Iterator[tuple[str, Block | Range]]:
+    """Each Block and Range under `value`, parents first, through dataclass fields and tuples."""
+    if isinstance(value, Range):
+        yield path, value
+    elif isinstance(value, tuple):
+        for index, each in enumerate(value):
+            yield from walk(each, f"{path}[{index}]")
+    elif is_dataclass(value) and not isinstance(value, type):
+        if isinstance(value, Block):
+            yield path, value
+        for item in fields(value):
+            yield from walk(getattr(value, item.name), join(path, item.name))

elecdef/_coil.py

@@ -0,0 +1,52 @@
+"""The Coil block: the drive of a relay or contactor, with its A1 and A2 pins."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from elecdef._block import Block, figure
+from elecdef._connection import Connection
+from elecdef._product import Symbol
+from elecdef._quantity import Kind
+from elecdef._range import Range, Ranges
+from elecdef.pins import Link, Pin, PinRole
+from elecdef.vocab import CoilKind, Suppression
+
+__all__ = ["Coil"]
+
+
+@dataclass(frozen=True)
+class Coil(Block):
+    """One coil: kind, drive figures, suppression, and the pins computed from kind and suppression.
+
+    `own_pins` holds only pins the author gave; with none, `pins` is A1 and A2 read on every access.
+    """
+
+    needs: ClassVar[tuple[str, ...]] = ("voltage",)
+
+    kind: CoilKind | None = None
+    voltage: Ranges = figure(Kind.VOLTAGE, many=True)
+    pick_up: Range | None = figure(Kind.RATIO)
+    drop_out: Range | None = figure(Kind.RATIO)
+    resistance: Range | None = figure(Kind.RESISTANCE)
+    power: Ranges = figure(Kind.POWER, many=True)
+    apparent_power: Ranges = figure(Kind.APPARENT_POWER, many=True)
+    operate_time: Range | None = figure(Kind.TIME)
+    release_time: Range | None = figure(Kind.TIME)
+    suppression: Suppression | None = None
+    connection: Connection | None = None
+    own_pins: tuple[Pin, ...] = ()
+    symbol: Symbol | None = None
+
+    @property
+    def pins(self) -> tuple[Pin, ...]:
+        """The author's `own_pins`, else A1 and A2 (PLUS and MINUS for a DC coil with a diode)."""
+        if self.own_pins:
+            return self.own_pins
+        polar = self.kind is CoilKind.DC and self.suppression is Suppression.DIODE
+        first, second = (PinRole.PLUS, PinRole.MINUS) if polar else (PinRole.COIL, PinRole.COIL)
+        return Pin("A1", first), Pin("A2", second)
+
+    @property
+    def links(self) -> tuple[Link, ...]:
+        """A coil joins no pins."""
+        return ()

elecdef/_connection.py

@@ -0,0 +1,28 @@
+"""The Connection block: how a conductor or a pin is attached."""
+
+from dataclasses import dataclass
+
+from elecdef._block import Block, figure
+from elecdef._quantity import Kind, Quantity
+from elecdef._range import Range, Ranges
+from elecdef.vocab import ConductorMaterial, ScrewSize, Technology
+
+__all__ = ["Connection"]
+
+
+@dataclass(frozen=True)
+class Connection(Block):
+    """One connection point: its technology, conductor range, strip length and torque.
+
+    Every field is unfilled by default, so a leaf states only its technology.
+    """
+
+    technology: Technology | None = None
+    conductor: Ranges = figure(Kind.AREA, many=True)
+    conductor_awg: Ranges = figure(Kind.GAUGE, many=True)
+    conductors_per_clamp: int | None = None
+    strip_length: Quantity | None = figure(Kind.LENGTH)
+    torque: Range | None = figure(Kind.TORQUE)
+    screw: ScrewSize | None = None
+    pitch: Quantity | None = figure(Kind.LENGTH)
+    material: ConductorMaterial | None = None

elecdef/_contact.py

@@ -0,0 +1,69 @@
+"""The Contact block: one switching element, with the pins its number and scheme give."""
+
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from elecdef._block import Block, figure
+from elecdef._connection import Connection
+from elecdef._product import Symbol
+from elecdef._quantity import Kind
+from elecdef._range import Range, Ranges
+from elecdef.pins import Link, Marking, Pin, contact_pins
+from elecdef.vocab import ContactFeature, ContactForm, ContactMaterial
+
+__all__ = ["Contact"]
+
+_MAX_N = 9
+
+
+@dataclass(frozen=True)
+class Contact(Block):
+    """One contact: form, ratings per condition, and the pins computed from number and scheme.
+
+    `own_pins` holds only what the author gave; `pins` is read from `number` and `scheme` each time.
+    """
+
+    needs: ClassVar[tuple[str, ...]] = ("switching",)
+
+    form: ContactForm | None = None
+    features: frozenset[ContactFeature] = field(default_factory=frozenset)
+    switching: Ranges = figure(Kind.CURRENT, many=True)
+    voltage: Range | None = figure(Kind.VOLTAGE)
+    min_load_voltage: Range | None = figure(Kind.VOLTAGE)
+    min_load_current: Range | None = figure(Kind.CURRENT)
+    material: ContactMaterial | None = None
+    mechanical_life: int | None = None
+    electrical_life: int | None = None
+    connection: Connection | None = None
+    number: int | None = None
+    scheme: Marking | None = None
+    own_pins: tuple[Pin, ...] = ()
+    symbol: Symbol | None = None
+
+    def __post_init__(self) -> None:
+        """Check the figures, then refuse a number or form the scheme cannot mark."""
+        super().__post_init__()
+        number = self.number
+        if number is not None and (
+            not isinstance(number, int) or isinstance(number, bool) or not 1 <= number <= _MAX_N
+        ):
+            message = "number is an int from 1 to 9"
+            raise TypeError(message)
+        self._computed()
+
+    def _computed(self) -> tuple[tuple[Pin, ...], tuple[Link, ...]]:
+        """The pins and links read from form, number and scheme; empty when any is unset."""
+        form, number, scheme = self.form, self.number, self.scheme
+        if self.own_pins or form is None or number is None or scheme is None:
+            return (), ()
+        return contact_pins(form, number, scheme)
+
+    @property
+    def pins(self) -> tuple[Pin, ...]:
+        """The author's `own_pins`, else the pins of the contact's form, number and scheme."""
+        return self.own_pins or self._computed()[0]
+
+    @property
+    def links(self) -> tuple[Link, ...]:
+        """The links of the computed pins; none with `own_pins`."""
+        return self._computed()[1]

elecdef/_device.py

@@ -0,0 +1,36 @@
+"""The Device block: pins and links given outright, the typed fallback for a thing with no block."""
+
+from dataclasses import dataclass
+
+from elecdef._block import Block
+from elecdef._body import Body
+from elecdef._connection import Connection
+from elecdef._product import Symbol
+from elecdef._rating import Rating
+from elecdef.pins import Link, Pin
+
+__all__ = ["Device"]
+
+
+@dataclass(frozen=True)
+class Device(Block):
+    """A thing with no block of its own yet: its pins and links are stored as given.
+
+    Every field is unfilled by default.
+    """
+
+    pins: tuple[Pin, ...] = ()
+    links: tuple[Link, ...] = ()
+    rating: Rating | None = None
+    connection: Connection | None = None
+    body: Body | None = None
+    symbol: Symbol | None = None
+
+    def __post_init__(self) -> None:
+        """Refuse pins or links that are not a tuple of Pin or Link."""
+        super().__post_init__()
+        for name, kind in (("pins", Pin), ("links", Link)):
+            value = getattr(self, name)
+            if not (isinstance(value, tuple) and all(isinstance(each, kind) for each in value)):
+                message = f"{name} is a tuple of {kind.__name__}"
+                raise TypeError(message)

elecdef/_issue.py

@@ -0,0 +1,26 @@
+"""Issues as values: what `check` and `pick` report instead of raising."""
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class IssueCode(Enum):
+    """The closed set of issue codes; `check` reports the first six, `pick` the last two."""
+
+    END_ORDER = auto()
+    DUPLICATE_MARKING = auto()
+    BAD_MARKING = auto()
+    DANGLING_LINK = auto()
+    MISSING_FIGURE = auto()
+    UNKNOWN_CLASS = auto()
+    NO_RATING = auto()
+    AMBIGUOUS_RATING = auto()
+
+
+@dataclass(frozen=True)
+class Issue:
+    """One finding: a code, a message and the subject path it concerns, such as `coil.voltage`."""
+
+    code: IssueCode
+    message: str
+    subject: str