cad 0.10.0__py3-none-any.whl

cad/__init__.py

@@ -0,0 +1,100 @@
+"""cad: CAD models as Python, built by its engine (``cad.engine``) into documents (``.xbf``)
+and the files they declare.
+
+The root exports exactly the engine's surface -- ``model``, the decorators (``xbf``, ``step``,
+``glb``, ``stl``, ``threemf``, ``dxf``), ``memo``, face painting (``paint``), the readers (``read_step``, ``read_xbf``, ``read_mesh``) -- its operations on
+documents as functions (``export``, ``snapshot``, ``inspect``) and ``__version__``; process
+control (``cad serve``, ``status``, ``stop``, ``server``) is the ``cad`` command's alone. Two
+namespaces hold the standards' names: ``cad.ap242`` the mechanism's (``mechanism_state``,
+``configuration_sequence``, ``gear_pair``, ``rack_and_pinion_pair``, ``screw_pair``, ``posed``) and
+``cad.gltf`` a GLB's own ``animation``. Every name loads on first use: ``import cad``
+imports no CAD kernel, and ``import build123d`` binds a module the kernel loads into on its
+first attribute (``_internal/lazy_kernel.py``).
+"""
+
+from functools import cache as _cache
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+# Before anything imports build123d, which every entry point of the library eventually does:
+# build123d parses EVERY font in the system font folders at import time, with no
+# per-file guard, so one malformed file aborts the import and every cad command
+# with it (issue #322, upstream in build123d's register_folder), as does a font with
+# no family name, whose empty name OCCT refuses (#636). This hides the fonts build123d
+# cannot register from that one listing.
+#
+# It belongs here rather than in a launcher because the `cad` command, the engine's
+# warm workers and `python -m cad.X` children all reach the library by different routes, and a
+# fix that covered only one of them would leave the builds it spawns still broken.
+#
+# Cost where nothing is wrong: one str.endswith per glob call. CAD_FONT_GUARD=0
+# opts out.
+from cad._internal.font_scan import install_font_guard as _install_font_guard
+from cad._internal.lazy_kernel import install as _install_lazy_kernel
+
+# ``import build123d as bd`` binds a module the kernel loads into on its first attribute
+# (``_internal/lazy_kernel.py``). The wheel's cad-lazy-kernel.pth installs it at interpreter
+# start; this covers an editable install, where that file is not placed. Idempotent.
+_install_lazy_kernel()
+del _install_lazy_kernel
+
+_install_font_guard()
+del _install_font_guard
+
+# The library installs nothing of the server's: what the engine's verbs did is told to the functions in
+# cad.engine.api.observers, which the server's commands fill (``cad_server._internal.engine_telemetry``),
+# and a process the server did not start -- a model's own, in the CAD kernel environment -- counts nothing.
+
+# The engine's surface (``cad.engine.__all__``) and its operations on documents as functions
+# (``cad.engine.api``).
+_ENGINE = ("model", "xbf", "memo", "step", "glb", "stl", "threemf", "dxf", "paint",
+           "read_step", "read_xbf", "read_mesh")
+_VERBS = ("export", "snapshot", "inspect")
+
+__all__ = [
+    "__version__",
+    *_ENGINE,
+    *_VERBS,
+]
+
+
+def __getattr__(name: str):
+    if name in _ENGINE:
+        import cad.engine as _engine
+
+        return getattr(_engine, name)
+    if name in _VERBS:
+        from cad.engine import api
+
+        return getattr(api, name)
+    if name == "__version__":
+        return _resolve_version()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Its public names (``__all__``) and the submodules imported so far: what ``dir()`` and
+    completion offer, without loading any of them, nor the kernel."""
+    return sorted({*__all__, *(name for name, value in globals().items() if name.startswith("__")
+                               or getattr(value, "__name__", "").startswith(__name__ + "."))})
+
+
+if _TYPE_CHECKING:
+    # Mirrors the lazy __getattr__ above so type checkers and editors see the root exports
+    # without importing OCP. Every name here must have a branch there, and comes from the
+    # module that defines it.
+    from cad.engine.api import export, inspect, snapshot
+    from cad.engine.model import (dxf, glb, memo, model, paint, read_step, read_xbf, step, stl, threemf, xbf)
+    from cad.engine.reader import read_mesh
+
+
+@_cache
+def _resolve_version() -> str:
+    """The version declared beside this very package (``_internal.version.declared_version``):
+    the source tree's pyproject for a checkout, the dist-info beside it for an install.
+    Never the first ``cad`` metadata on ``sys.path``, which can be another install's.
+    Resolved once per process: the code that answers cannot change under a running one."""
+    import pathlib
+
+    from cad._internal.version import declared_version
+
+    return declared_version(pathlib.Path(__file__).resolve().parent)

cad/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Internal cadgen implementation modules.
+
+Everything under ``cad._internal`` is private: no import stability is
+promised between releases. The supported API is the top-level ``cadgen``
+modules and the root ``cadgen`` exports.
+"""

cad/_internal/atomic_replace.py

@@ -0,0 +1,137 @@
+"""The one atomic rename every file cadgen writes outside the engine goes through.
+
+The settings, the model library, the channel record, the telemetry spool and batches, a Quick
+Edit packet: each is written to a temp file and renamed into place, so a reader never sees a
+half-written payload. (The engine keeps its own copy of this rule, ``cad.engine.atomic_replace``:
+it imports nothing of cadgen.) On a Windows SMB share that rename is not reliably atomic-and-instant:
+the redirector can still hold the handle Python just closed, and the rename loses with
+``WinError 32`` (ERROR_SHARING_VIOLATION, "file is being used by another process") -- issue #241,
+where 8 workers failed every time on a NAS and one worker succeeded.
+
+Deliberately narrow:
+
+* only ``WinError 32``, and ``WinError 5`` onto an existing FILE, retry (see below for the
+  second). A denial with no file in the way -- a read-only folder, a directory at the target --
+  or a missing directory is a real error and must surface at once, not 350 ms later.
+* the attribute does not exist off Windows, so this is exactly ``os.replace`` on POSIX.
+* five attempts over 750 ms, then the original error propagates.
+
+The window is sized for the TAIL, not the median (issue #274): measured on a Synology SMB share,
+the median blocked rename waited 31 ms, p99 265 ms, max 797 ms. The tail is long and thin, so any
+finite window eventually loses to it, and a bigger constant is not the answer: when the ladder is
+exhausted, ``replace_atomic`` copies the temp file sideways under a name the server has never seen
+and runs the ladder once more on the copy. The violation belongs to the handle the server still
+holds on the ORIGINAL temp file; the copy carries no handle of its own.
+
+The DESTINATION has its own failure, and it answers with a different code. NTFS refuses to
+rename over a file that any process holds open -- ``MoveFileEx`` without POSIX semantics, which is
+what ``os.replace`` is -- and says ``WinError 5`` (ERROR_ACCESS_DENIED), not 32: two processes
+writing one settings file each read what they just wrote. The hold is a read that ends in
+milliseconds, so the same ladder waits it out; the retry is keyed on a FILE at the target, because
+that is the only case where a ``5`` can be somebody else's handle.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import time
+from pathlib import Path
+
+# ERROR_SHARING_VIOLATION: the file is open in another process -- or, on SMB, was open a moment
+# ago and the server has not caught up.
+WINDOWS_SHARING_VIOLATION = 32
+# ERROR_ACCESS_DENIED: what a rename answers when another process holds the DESTINATION open
+# (or is renaming onto it). Retried only when a file is there -- see the module docstring.
+WINDOWS_ACCESS_DENIED = 5
+RETRY_DELAYS_SECONDS = (0.05, 0.1, 0.2, 0.4)
+
+
+def temp_suffix() -> str:
+    """A collision-free suffix for a sibling temp file, ending in ``.tmp``.
+
+    ``os.urandom`` rather than a clock: two writes inside one clock tick would otherwise collide,
+    and the rescue below depends on the new name being genuinely new rather than on the timer's
+    resolution. The ``.tmp`` ending matters too -- ``.gitignore`` carries ``*.tmp``, so a temp
+    file leaked in the deep tail stays invisible to ``git add -A``.
+    """
+    return f".{os.getpid()}.{os.urandom(4).hex()}.tmp"
+
+
+def _held(error: OSError, target_path: Path | str) -> bool:
+    """Whether a refused rename is a handle someone will let go of.
+
+    A sharing violation always is. A denial is only when a FILE is at the target: that is the
+    code NTFS gives a rename over a file another process has open. With nothing there, or a
+    directory in the way, a denial is a real one.
+    """
+    code = getattr(error, "winerror", None)
+    if code == WINDOWS_SHARING_VIOLATION:
+        return True
+    return code == WINDOWS_ACCESS_DENIED and os.path.isfile(target_path)
+
+
+def _run_ladder(temp_path: Path | str, target_path: Path | str) -> OSError | None:
+    """Run the bounded retry, returning the held-handle refusal it could not beat.
+
+    Any other error propagates at once: a real denial or a missing directory must surface
+    immediately, not 750 ms later.
+    """
+    for delay in (*RETRY_DELAYS_SECONDS, None):
+        try:
+            os.replace(temp_path, target_path)
+            return None
+        except OSError as error:
+            if not _held(error, target_path):
+                raise
+            if delay is None:
+                return error
+            time.sleep(delay)
+    return None
+
+
+def replace_atomic(temp_path: Path | str, target_path: Path | str) -> None:
+    """``os.replace`` with a bounded retry, then one retry from a copy the server has not seen."""
+    blocked = _run_ladder(temp_path, target_path)
+    if blocked is None:
+        return
+
+    source = Path(temp_path)
+    fresh = source.with_name(f"{source.name}{temp_suffix()}")
+    try:
+        shutil.copyfile(source, fresh)
+    except OSError:
+        # The source is pinned for reading too, so there is nothing left to try. Report the
+        # rename failure, which is the one the caller was waiting on.
+        raise blocked from None
+
+    # Best effort: the handle that blocked the rename usually blocks this as well.
+    with contextlib.suppress(OSError):
+        source.unlink(missing_ok=True)
+
+    try:
+        if _run_ladder(fresh, target_path) is not None:
+            raise blocked
+    finally:
+        with contextlib.suppress(OSError):
+            fresh.unlink(missing_ok=True)
+
+
+def write_bytes_atomic(target_path: Path, payload: bytes) -> None:
+    """Write ``payload`` to ``target_path`` through a temp file in the same directory.
+
+    Same directory on purpose: a rename across filesystems is not atomic, and a temp dir on
+    another volume would silently turn this into a copy.
+    """
+    resolved = Path(target_path)
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = resolved.with_name(f"{resolved.name}{temp_suffix()}")
+    try:
+        temp_path.write_bytes(payload)
+        replace_atomic(temp_path, resolved)
+    finally:
+        # Suppressed: on Windows the handle that blocks a rename blocks the delete too, and
+        # letting that escape here would mask the rename failure the caller needs to see.
+        with contextlib.suppress(OSError):
+            temp_path.unlink(missing_ok=True)

cad/_internal/counts.py

@@ -0,0 +1,36 @@
+"""What the library counts for telemetry, told to the server's telemetry where the server installed it.
+
+The library sends nothing and keeps nothing: a drawing made, and a mistake of cadgen's own code met making
+one, are handed to ``TELEMETRY`` -- the server's ``cad_server.analytics``, which its commands install here
+(``cad_server._internal.engine_telemetry.install``) -- and dropped where none is installed: a model's own
+process, in the CAD kernel environment, has only the library. Neither ever fails, nor changes, what it
+counts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# The server's telemetry (``cad_server.analytics``: ``report`` and ``hand_over``), or None: nothing is counted.
+TELEMETRY: Any = None
+
+
+def report(error: BaseException, where: str, **options: Any) -> None:
+    """A mistake of cadgen's own code, told to the server's telemetry (``analytics.report``). Never raises."""
+    if TELEMETRY is None:
+        return
+    try:
+        TELEMETRY.report(error, where, **options)
+    except Exception:  # noqa: BLE001 - a crash report never adds a failure to one
+        pass
+
+
+def hand_over(counts: dict[str, Any]) -> None:
+    """What a model's process counted (``{"features": ["drawing"]}``), kept with a command's counts by the
+    server's telemetry (``analytics.hand_over``). Never raises."""
+    if TELEMETRY is None:
+        return
+    try:
+        TELEMETRY.hand_over(counts)
+    except Exception:  # noqa: BLE001 - a count never fails what it counts
+        pass

cad/_internal/font_scan.py

@@ -0,0 +1,146 @@
+"""Keep the fonts build123d cannot register out of the scan ``import build123d`` runs.
+
+build123d registers EVERY font in the system font folders at import time:
+``build123d/text.py`` ends with ``available_fonts = FontManager().available_fonts``,
+whose ``__init__`` calls ``register_system_fonts() -> register_folder() ->
+register_font()``, and ``register_font`` hands each file straight to
+``fontTools.ttLib.TTFont`` with no per-file guard. One malformed file, or one font with
+no family name (whose empty name OCCT refuses, #636), therefore takes down
+``import build123d`` itself, and with it every cad command -- on Windows, where that
+scan is the one platform build123d runs it on (OCCT does not pick up user fonts there).
+
+``install_font_guard`` hides such a file from the one folder listing build123d makes;
+``python -m cad.check_fonts`` names it. The permanent fix belongs upstream, in
+``register_folder``.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+
+
+def system_font_dirs() -> list[str]:
+    """The folders build123d scans, mirrored from ``register_system_fonts``.
+
+    Kept in the same order so the report matches the order the scan would hit them.
+    ``os.getlogin()`` is what build123d uses for the per-user Windows folder; it
+    raises with no controlling terminal, so the fallback keeps the diagnostic alive
+    where the thing it describes still runs.
+    """
+    if platform.system() == "Windows":
+        try:
+            user = os.getlogin()
+        except OSError:
+            user = os.environ.get("USERNAME", "")
+        dirs = ["C:/Windows/Fonts"]
+        if user:
+            dirs.append(f"C:/Users/{user}/AppData/Local/Microsoft/Windows/Fonts")
+        return dirs
+    if platform.system() == "Darwin":
+        return ["/System/Library/Fonts", "/Library/Fonts"]
+    return ["/system/fonts", "/usr/share/fonts", "/usr/local/share/fonts"]
+
+
+# build123d's register_folder globs `"*" + ext` with NO dot, so the patterns it passes
+# end in a bare "ttf"/"otf"/"ttc". Matching on ".ttf" here silently disables the guard,
+# which is exactly how the first version of it did nothing.
+_GLOB_PATTERN_SUFFIXES = ("ttf", "otf", "ttc")
+
+_ENV_DISABLE = "CAD_FONT_GUARD"
+
+skipped_fonts: list[str] = []
+
+
+def family_name(font) -> str:
+    """The family name build123d registers a font under, or "" when it has none.
+
+    Follows ``_get_font_faces`` in build123d/text.py: the first decodable, non-empty
+    nameID 16 (preferred family), else the first decodable, non-empty nameID 1. The empty
+    check runs on the raw value and the strip comes last, as there, so a blank preferred
+    name is "" even when nameID 1 has one. OCCT refuses an empty name, which is #636.
+    """
+    family = ""
+    preferred = ""
+    for record in font["name"].names:
+        try:
+            value = record.toUnicode()
+        except UnicodeDecodeError:
+            continue
+        if record.nameID == 1 and family == "":
+            family = value
+        elif record.nameID == 16 and preferred == "":
+            preferred = value
+    return (preferred if preferred != "" else family).strip()
+
+
+def _font_registers(path: str) -> bool:
+    """Whether build123d could register this file: it parses, and every face has a name.
+
+    The name table is read, not just the file opened: ``TTFont`` is lazy, so a broken
+    table directory behind a valid sfnt header constructs fine and fails later, inside
+    ``_get_font_faces``, whose first act is ``ft_font["name"].names``. A face with no
+    family name fails there too, when OCCT is handed its empty name.
+    """
+    try:
+        from fontTools.ttLib import TTFont, ttCollection
+    except ImportError:
+        # No fontTools means no font scan to protect; let everything through.
+        return True
+    try:
+        if os.path.splitext(path)[1].strip(".").lower() == "ttc":
+            fonts = list(ttCollection.TTCollection(path))
+        else:
+            fonts = [TTFont(path)]
+        for font in fonts:
+            if not family_name(font):
+                return False
+    except Exception:  # noqa: BLE001 - any parse failure is one build123d would hit
+        return False
+    return True
+
+
+def install_font_guard() -> bool:
+    """Hide fonts build123d cannot register from the scan it runs at import time.
+
+    ``register_folder`` lists a folder with ``glob.glob`` and hands every result
+    straight to ``fontTools``. ``glob`` is resolved on the module object at call time,
+    so filtering that one listing keeps a file build123d cannot register from ever being
+    opened -- the file is skipped, the rest of the folder still registers, and neither a
+    malformed font nor an empty name reaches OCCT's font table.
+
+    This is the seam because it is the only point between "list the files" and "open
+    one". Replacing ``TTFont`` instead cannot work: a stand-in has to survive
+    ``_get_font_faces``, and one with an empty name table registers an empty-named
+    ``Font_SystemFont`` into OCCT's global manager.
+
+    Returns True when the guard is installed. Idempotent, and a no-op when
+    ``CAD_FONT_GUARD=0``.
+    """
+    if os.environ.get(_ENV_DISABLE) == "0":
+        return False
+
+    import glob
+
+    if getattr(glob.glob, "_cadgen_font_guard", False):
+        return True
+
+    real_glob = glob.glob
+
+    def guarded_glob(pathname, *args, **kwargs):
+        results = real_glob(pathname, *args, **kwargs)
+        # One string check for every other glob in the process. Only a font listing
+        # pays for a parse, and only build123d asks for one.
+        if not str(pathname).lower().endswith(_GLOB_PATTERN_SUFFIXES):
+            return results
+        keep = []
+        for path in results:
+            if _font_registers(path):
+                keep.append(path)
+            elif path not in skipped_fonts:
+                skipped_fonts.append(path)
+        return keep
+
+    guarded_glob._cadgen_font_guard = True  # type: ignore[attr-defined]
+    glob.glob = guarded_glob  # type: ignore[assignment]
+    return True

cad/_internal/lazy_kernel.py

@@ -0,0 +1,99 @@
+"""``import build123d`` binds the module; the kernel loads on its first attribute.
+
+A model script's module body should cost nothing until the engine has decided whether to build
+-- in the process that only hands the build to the warm worker, it never loads the kernel at
+all -- yet the idiom every build123d author writes is ``import build123d as bd`` at the top.
+This ``sys.meta_path`` finder makes that idiom free: for the top-level names ``build123d`` and
+``OCP`` alone it returns the ordinary spec (``PathFinder``'s) with its loader wrapped in
+``importlib.util.LazyLoader``, so the import binds a module whose body runs on the first
+attribute anything reads from it (``bd.Box``), in whichever process that is.
+
+``from build123d import Box`` reads an attribute to bind ``Box``, so it loads the kernel there and
+then, as without the finder; ``import OCP.Standard`` loads ``OCP`` to find its submodule, and the
+submodule as ever. Only the top-level packages are lazy: a submodule is imported when asked.
+
+Every later ``import build123d`` -- a project's helper module importing it as the script did --
+binds the same module and loads nothing. The import system reads a module's ``__spec__`` on each
+import that finds it in ``sys.modules`` (to wait on one still initializing), and the standard
+library's lazy module loads on any attribute, so the module is a ``KernelModule``, which answers
+``__spec__`` as it stands and hands every other first read to the standard library's load.
+
+Installed twice, harmlessly (``install`` is idempotent): by ``cad-lazy-kernel.pth`` in the
+site-packages of an environment the library is installed into, before any import, and by the library's
+package ``__init__`` for an editable install, where a wheel's ``.pth`` is not placed. Importing
+this module imports no kernel.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import threading
+import types
+from importlib.machinery import PathFinder
+from typing import Any
+
+KERNEL = ("build123d", "OCP")
+
+
+_SWAP = threading.Lock()
+
+
+class KernelModule(types.ModuleType):
+    """A lazy kernel module: ``__spec__`` read as it stands, every other attribute the first
+    read of the standard library's lazy module, which loads it."""
+
+    def __getattribute__(self, attr: str) -> Any:
+        if attr == "__spec__":
+            return object.__getattribute__(self, attr)
+        with _SWAP:
+            if type(self) is KernelModule:  # by type(): reading ``__class__`` would come back here
+                self.__class__ = importlib.util._LazyModule  # noqa: SLF001
+        try:
+            return getattr(self, attr)
+        except AttributeError as error:
+            # A name the module lacks is the asker's mistake, raised from here as Python raises it,
+            # never as a failure of this frame's own (``analytics.signature``).
+            raise error.with_traceback(None) from None
+
+    def __delattr__(self, attr: str) -> None:
+        self.__getattribute__(attr)
+        delattr(self, attr)
+
+
+class KernelLoader(importlib.util.LazyLoader):
+    """``LazyLoader``, its module a ``KernelModule``."""
+
+    def exec_module(self, module: types.ModuleType) -> None:
+        super().exec_module(module)
+        module.__class__ = KernelModule
+
+
+class LazyKernelFinder:
+    """Finds ``build123d`` and ``OCP`` as ``PathFinder`` does, their loaders made lazy."""
+
+    def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> Any:
+        if fullname not in KERNEL:
+            return None
+        spec = PathFinder.find_spec(fullname, path, target)
+        if spec is None or spec.loader is None or not hasattr(spec.loader, "exec_module"):
+            return None  # nothing to defer: the next finder imports it as ever
+        spec.loader = KernelLoader(spec.loader)
+        return spec
+
+
+def install() -> None:
+    """Put the finder first on ``sys.meta_path``, once."""
+    if not any(isinstance(finder, LazyKernelFinder) for finder in sys.meta_path):
+        sys.meta_path.insert(0, LazyKernelFinder())
+
+
+def loaded(name: str) -> bool:
+    """Whether ``name`` is imported and its body has run: a lazy module bound by ``import`` and
+    never read from is not loaded."""
+    module = sys.modules.get(name)
+    # By its exact type: an isinstance check that misses reads ``__class__``, which loads it.
+    return module is not None and type(module) not in (KernelModule, importlib.util._LazyModule)  # noqa: SLF001
+
+
+install()

cad/_internal/program.py

@@ -0,0 +1,71 @@
+"""``python -P -m cad._internal.program ARGS``: ``python ARGS`` -- a script, ``-m MODULE`` or ``-c CODE`` --
+with the program's own folder (the script's; for a module or code, the working folder) LAST on the module
+search path, where Python puts it first.
+
+So a project's module that bears the library's name -- a ``cad.py`` beside a model -- never stands in for
+the library, and the program's own modules still import by their names. ``-P`` keeps the working folder
+off the path from the interpreter's start. The server's ``run`` verb runs every program so, and the
+engine's worker seats a model's folder the same way (``cad.engine.model.seat``).
+
+A program written for cadgen 0.7 stops at its first import of a name 0.8 took out of ``cadgen``
+(``build123d``, ``revolute``, ``read_scene``, ...): the failure is said as Python says it, then one line
+naming the guide from 0.7 to 0.8 (``EARLIER``).
+"""
+
+from __future__ import annotations
+
+import os
+import runpy
+import sys
+import traceback
+import types
+
+USAGE = "usage: python -P -m cad._internal.program SCRIPT [ARGS...] | -m MODULE [ARGS...] | -c CODE [ARGS...]"
+
+
+# The guide a program written for cadgen 0.7 is migrated by.
+GUIDE = "https://github.com/earthtojake/text-to-cad/blob/main/docs/migrations/migrating-0.7-to-0.8.md"
+EARLIER = f"A program written for cadgen 0.7 imports names 0.8 took out; migrate it: {GUIDE}"
+
+
+def earlier(error: BaseException) -> bool:
+    """Whether ``error`` is an import from ``cadgen`` that failed: a name or a module 0.7 had."""
+    name = getattr(error, "name", None) or ""
+    return isinstance(error, ImportError) and (name == "cadgen" or name.startswith("cadgen."))
+
+
+def last(folder: str) -> None:
+    """``folder`` at the end of the module search path, moved there if the path holds it already."""
+    while folder in sys.path:
+        sys.path.remove(folder)
+    sys.path.append(folder)
+
+
+def main(argv: list[str]) -> None:
+    if not argv or (argv[0] in ("-m", "-c") and len(argv) < 2) or (argv[0].startswith("-") and argv[0] not in ("-m", "-c")):
+        raise SystemExit(USAGE)
+    if argv[0] == "-m":
+        last(os.getcwd())
+        sys.argv = [argv[1], *argv[2:]]  # runpy names the module's file in argv[0], as ``python -m`` does
+        runpy.run_module(argv[1], run_name="__main__", alter_sys=True)
+    elif argv[0] == "-c":
+        last(os.getcwd())
+        sys.argv = ["-c", *argv[2:]]
+        program = types.ModuleType("__main__")
+        sys.modules["__main__"] = program
+        exec(compile(argv[1], "<string>", "exec"), program.__dict__)  # noqa: S102 -- python -c, as asked
+    else:
+        last(os.path.dirname(os.path.abspath(argv[0])))
+        sys.argv = list(argv)
+        runpy.run_path(argv[0], run_name="__main__")
+
+
+if __name__ == "__main__":
+    try:
+        main(sys.argv[1:])
+    except ImportError as error:
+        if not earlier(error):
+            raise
+        traceback.print_exc()
+        print(EARLIER, file=sys.stderr)
+        sys.exit(1)