jitx 4.0.0__py3-none-any.whl

jitx/__init__.py

@@ -0,0 +1,212 @@
+"""
+JITX Python API
+===============
+
+The JITX Python API is a set of classes that can be used to build a design in
+Python. The core principle of the API is that, when run, your code constructs
+an object tree that is then inspected. This means that creating an object and
+attaching them to other objects is what drives the construction of the design,
+and not function calls. The root of the tree is an instance of a
+:py:class:`~jitx.design.Design` subclass. The JITX runtime will inspect your
+project looking for Design subclasses which are then instantiated on request.
+
+The inspection mechanism will traverse lists, tuples, and dictionaries, as
+well, thus objects can be added to arrays and dictionaries as needed when
+building the object tree.
+
+The API is designed to be as simple as possible, and to be as close to Python
+as possible. The API is designed to be used with a Python language server, such
+as PyLance/pyright, to provide autocompletion and type checking.
+
+.. note::
+
+    There are a few mechanisms designed to make API usage cleaner by allowing
+    instantiated objects as class attributes, but there are caveats to be aware
+    of when doing more involved logic, and when in doubt, all logic can also be
+    placed in the initializer of the class. Runtime errors involving an
+    unexpected "Instantiable" object is indicative of this type of error.
+"""
+
+from .anchor import Anchor as Anchor
+from .board import Board as Board
+from .circuit import Circuit as Circuit, CurrentCircuit
+from .component import Component as Component, CurrentComponent
+from .constraints import (
+    IsBoardEdge as IsBoardEdge,
+    IsCopper as IsCopper,
+    IsHole as IsHole,
+    IsNeckdown as IsNeckdown,
+    IsPad as IsPad,
+    IsPour as IsPour,
+    IsThroughHole as IsThroughHole,
+    IsTrace as IsTrace,
+    IsVia as IsVia,
+    SquareViaStitchGrid as SquareViaStitchGrid,
+    Tag as Tag,
+    Tags as Tags,
+    TriangularViaStitchGrid as TriangularViaStitchGrid,
+    ViaFencePattern as ViaFencePattern,
+    design_constraint as design_constraint,
+)
+from .container import Composite as Composite, Container as Container
+from .context import ContextProperty
+from .copper import Copper as Copper, Pour as Pour
+from .design import Design as Design, DesignContext
+from .error import UserCodeException as UserCodeException
+from .feature import (
+    Courtyard as Courtyard,
+    Custom as Custom,
+    Cutout as Cutout,
+    Finish as Finish,
+    Glue as Glue,
+    KeepOut as KeepOut,
+    Paste as Paste,
+    Silkscreen as Silkscreen,
+    Soldermask as Soldermask,
+)
+from .inspect import decompose as decompose, extract as extract, visit as visit
+from .landpattern import (
+    Landpattern as Landpattern,
+    Pad as Pad,
+    PadMapping as PadMapping,
+)
+from .layerindex import LayerSet as LayerSet, Side as Side
+from .net import (
+    DiffPair as DiffPair,
+    Net as Net,
+    Port as Port,
+    provide as provide,
+    Provide as Provide,
+)
+from .placement import Placement as Placement, Positionable as Positionable
+from .shapes.composites import capsule as capsule, rectangle as rectangle
+from .shapes.primitive import (
+    Arc as Arc,
+    ArcPolygon as ArcPolygon,
+    ArcPolyline as ArcPolyline,
+    Circle as Circle,
+    Polygon as Polygon,
+    Polyline as Polyline,
+)
+from .substrate import Substrate as Substrate, SubstrateContext
+from .symbol import Pin as Pin, Symbol as Symbol, SymbolMapping as SymbolMapping
+from .toleranced import Toleranced as Toleranced
+from .transform import Point as Point, Transform as Transform
+from .via import Via as Via
+
+# the pattern used above
+#
+# from X import Class as Class
+#
+# is a convention to indicate to language servers that the name should be
+# reexported from the module and offered during autocompletion, as well as not
+# flagged as an unused import.
+
+
+class Current:
+    """
+    Context registry object, where each field is a property that will get
+    the currently registered context value. If no such context is currently
+    active, it will raise an exception. This is purely for convenience, the
+    contexts can be accessed directly.
+
+    The main purpose of this is to allow introspection of the environment. Note
+    that any accessed context value will be part of the memoization key, and
+    thus if the environment changes a memoized element will be reevaluated, and
+    thus use of current circuit or component should be used with care.
+
+    There is already an instance of this class, :py:data:`current`, which can
+    be used directly.
+    """
+
+    design = ContextProperty(DesignContext, lambda x: x.design)
+    "The current design being built"
+    substrate = ContextProperty(SubstrateContext, lambda x: x.substrate)
+    "The substrate of the current design"
+    circuit = ContextProperty(CurrentCircuit, lambda x: x.circuit)
+    "The current circuit being constructed"
+    component = ContextProperty(CurrentComponent, lambda x: x.component)
+    "The current component being constructed"
+
+    def __repr__(self):
+        return "Current"
+
+
+current = Current()
+"""Singleton, the "current" context registry."""
+
+# this can't be autogenerated at runtime, since the typechecker won't know what is
+# actually imported if someone does from jitx import *, thus they need to be
+# listed in the source file; please remember to update this if you add new
+# imports that should be reexported
+
+# grep '^\(from\|   \)' __init__.py | grep -o 'as [^, ]*\(,\|$\)' | sed -e 's/^as \([^,]*\).*$/    "\1",/'
+__all__ = [
+    "current",
+    # list below is generated with the grep command
+    "Anchor",
+    "Board",
+    "Circuit",
+    "Component",
+    "IsBoardEdge",
+    "IsCopper",
+    "IsHole",
+    "IsNeckdown",
+    "IsPad",
+    "IsPour",
+    "IsThroughHole",
+    "IsTrace",
+    "IsVia",
+    "SquareViaStitchGrid",
+    "Tag",
+    "Tags",
+    "TriangularViaStitchGrid",
+    "ViaFencePattern",
+    "design_constraint",
+    "Composite",
+    "Container",
+    "Copper",
+    "Pour",
+    "Design",
+    "UserCodeException",
+    "Courtyard",
+    "Custom",
+    "Cutout",
+    "Finish",
+    "Glue",
+    "KeepOut",
+    "Paste",
+    "Silkscreen",
+    "Soldermask",
+    "decompose",
+    "extract",
+    "visit",
+    "Landpattern",
+    "Pad",
+    "PadMapping",
+    "LayerSet",
+    "Side",
+    "DiffPair",
+    "Net",
+    "Port",
+    "provide",
+    "Provide",
+    "Placement",
+    "Positionable",
+    "capsule",
+    "rectangle",
+    "Arc",
+    "ArcPolygon",
+    "ArcPolyline",
+    "Circle",
+    "Polygon",
+    "Polyline",
+    "Substrate",
+    "Pin",
+    "Symbol",
+    "SymbolMapping",
+    "Toleranced",
+    "Point",
+    "Transform",
+    "Via",
+]

jitx/__main__.py

@@ -0,0 +1,165 @@
+# jitx/__main__.py
+from argparse import ArgumentParser
+from logging import basicConfig
+import sys
+
+from jitx.run import (
+    DesignBuilder,
+    DesignFactory,
+    DesignFinder,
+    DryRunBuilder,
+    json_formatter,
+    text_formatter,
+)
+from jitx.run.dependencies import sync_venv
+
+parser = ArgumentParser("jitx")
+parser.add_argument("--format", choices=["json", "text"])
+parser.add_argument(
+    "--logging",
+    type=str,
+    default="INFO",
+    choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+    help="Logging level",
+)
+
+subparser = parser.add_subparsers(dest="cmd")
+
+# find
+find_design_parser = subparser.add_parser("find")
+find_design_parser.add_argument("path", nargs="*")
+
+# build
+build_design_parser = subparser.add_parser("build")
+build_design_parser.add_argument("--dump")
+build_design_parser.add_argument("--dry", default=False, action="store_true")
+build_design_parser.add_argument("--host", type=str, default="localhost")
+build_design_parser.add_argument("--port", type=int)
+build_design_parser.add_argument("--uri", type=str)
+build_design_parser.add_argument("--socket", metavar="FILE", default=None, type=str)
+build_design_parser.add_argument("--no-dependency-check", action="store_true")
+build_design_parser.add_argument("--check-include-group", action="append", default=None)
+build_design_parser.add_argument("design", nargs="+")
+
+# build-all
+build_all_design_parser = subparser.add_parser("build-all")
+build_all_design_parser.add_argument("--host", type=str, default="localhost")
+build_all_design_parser.add_argument("--port", type=int)
+build_all_design_parser.add_argument("--uri", type=str)
+build_all_design_parser.add_argument("--socket", metavar="FILE", default=None, type=str)
+build_all_design_parser.add_argument("--generate-config", action="store_true")
+build_all_design_parser.add_argument("--no-dependency-check", action="store_true")
+build_all_design_parser.add_argument(
+    "--check-include-group", action="append", default=None
+)
+
+# upgrade-dependencies
+dependency_parser = subparser.add_parser(
+    "dependencies", help="Check or upgrade Python dependencies"
+)
+dependency_parser.add_argument(
+    "--upgrade",
+    action="store_true",
+    help="Upgrade to highest allowed (otherwise just check)",
+)
+dependency_parser.add_argument(
+    "--allow-prereleases",
+    "--pre",
+    action="store_true",
+    help="Include prereleases during resolution",
+)
+dependency_parser.add_argument(
+    "--check-include-group",
+    action="append",
+    default=None,
+    help="Optional-dependency group(s) to include (repeatable)",
+)
+dependency_parser.add_argument(
+    "--editable-install",
+    action="store_true",
+    help="Reinstall the current project in editable mode after upgrading dependencies",
+)
+
+build_config_parser = subparser.add_parser(
+    "run-config", help="Generate VSCode run and debug configuration"
+)
+
+args = parser.parse_args()
+basicConfig(level=args.logging)
+
+formatter = {"json": json_formatter, "text": text_formatter}.get(
+    args.format, text_formatter
+)
+
+if args.cmd == "find":
+    DesignFactory(DesignFinder(args.path), DryRunBuilder(), formatter=formatter).list()
+elif args.cmd == "build":
+    if not args.no_dependency_check:
+        sync_venv(
+            mode="check",
+            allow_prereleases=False,
+            include_optional_groups=args.check_include_group,
+        )
+
+    if args.dry:
+        builder = DryRunBuilder()
+    elif args.uri:
+        builder = DesignBuilder(uri=args.uri)
+    elif args.port:
+        builder = DesignBuilder(port=args.port, host=args.host)
+    elif args.socket:
+        builder = DesignBuilder(spec=args.socket)
+    else:
+        builder = DesignBuilder()
+
+    finder = DesignFinder(".")
+    factory = DesignFactory(finder, builder, formatter=formatter, dump=args.dump)
+    for design in args.design:
+        if design.endswith(".py"):
+            factory.by_file(design)
+        else:
+            factory.by_name(design)
+    factory.build()
+    if not factory.success:
+        sys.exit(1)
+
+elif args.cmd == "build-all":
+    if not args.no_dependency_check:
+        sync_venv(
+            mode="check",
+            allow_prereleases=False,
+            include_optional_groups=args.check_include_group,
+        )
+
+    finder = DesignFinder(".")
+    builder = (
+        DesignBuilder(uri=args.uri)
+        if args.uri
+        else DesignBuilder(port=args.port, host=args.host)
+        if args.port
+        else DesignBuilder()
+    )
+    factory = DesignFactory(finder, builder, formatter=formatter)
+    factory.add_all()
+    factory.build()
+    if args.generate_config:
+        from jitx.vscode.config import generate_config
+
+        generate_config()
+    if not factory.success:
+        sys.exit(1)
+
+elif args.cmd == "dependencies":
+    mode = "upgrade" if args.upgrade else "check"
+    sync_venv(
+        mode=mode,
+        allow_prereleases=bool(args.allow_prereleases),
+        include_optional_groups=args.check_include_group,
+        editable_install=args.editable_install,
+    )
+elif args.cmd == "run-config":
+    from jitx.vscode.config import generate_config
+
+    generate_config()
+else:
+    parser.print_help()

jitx/_instantiation.py

@@ -0,0 +1,105 @@
+from threading import local
+from typing import Self, Any
+from contextlib import contextmanager
+
+import os
+
+
+class InstantiationStructureException(Exception):
+    pass
+
+
+class InstantiationStructure:
+    class Frame:
+        def __init__(self, parent: Self | None = None):
+            self.parent = parent
+            self.context: dict[Any, Any] = {}
+            self.tracker: list[dict[Any, Any]] = []
+
+        def get(self, key):
+            if key in self.context:
+                value = self.context[key]
+            elif self.parent:
+                value = self.parent.get(key)
+            else:
+                value = None
+            if self.tracker:
+                self.tracker[-1][key] = value
+            return value
+
+    class InstantiationData(local):
+        def __init__(self):
+            super().__init__()
+            self.stack: list[InstantiationStructure.Frame] = []
+
+    def __init__(self):
+        self.data = self.InstantiationData()
+        self.generation = 0
+
+    def active(self):
+        return bool(self.data.stack)
+
+    @contextmanager
+    def activate(self):
+        if self.active():
+            raise InstantiationStructureException("Structure already active")
+        # for tracking lost objects
+        self.generation += 1
+        self.data.stack.append(self.Frame())
+        try:
+            yield
+        finally:
+            self.data.stack.clear()
+
+    @contextmanager
+    def require(self):
+        if self.active():
+            yield
+        else:
+            with self.activate():
+                yield
+
+    @contextmanager
+    def frame(self, frame: Frame | None = None):
+        self.push(frame)
+        try:
+            yield
+        finally:
+            self.pop()
+
+    def push(self, frame: Frame | None = None):
+        if not self.active():
+            raise InstantiationStructureException("Structure not active")
+        if frame is None:
+            frame = self.Frame(self.data.stack[-1])
+        self.data.stack.append(frame)
+
+    def pop(self):
+        self.data.stack.pop()
+
+    @property
+    def current_frame(self) -> Frame:
+        if not self.active():
+            raise InstantiationStructureException("Structure not active")
+        return self.data.stack[-1]
+
+    def get(self, key):
+        if not self.active():
+            raise InstantiationStructureException("Structure not active")
+        return self.data.stack[-1].get(key)
+
+    def set(self, key, value):
+        if not self.active():
+            raise InstantiationStructureException("Structure not active")
+        self.data.stack[-1].context[key] = value
+
+
+instantiation = InstantiationStructure()
+passive_representation = False
+if os.environ.get("JITX_PASSIVE_INSTANTIATION"):
+    # this is used to show representation of instantiable objects as their class
+    # name, rather than their "Instantiable" wrapper. The purpose of this is to
+    # get legible documentation. Enabling this during a debug sessions will
+    # likely be confusing, if there's a spurious "Instantiable" object causing
+    # whatever bug is being debugged.
+    passive_representation = True