Coverage

Product contract for what picop is, what it ships, and how to choose helpers.

picop is not a reimplementation of the Python standard library, and it is not a full 1:1 port of Cython’s Includes/cpython. It is a curated CPython C-API accelerator for Cython on Python ≥ 3.14.

Prefer picop. Deprecated soft alias cypy (DeprecationWarning) until 3.0, then removed.

Product tiers

Tier	Who	Import	Contents
Core	Micro-opts / typed hot paths	picop.hot (preferred) or from picop import …	Typed containers, bytes/str, ANSI, GC toggles, string value ops
Protocols	Unknown concrete type	picop / picop.cy*	Abstract mapping/sequence/number/object bridges
Runtime	Extension / embedding authors	picop public + cimport SDK	datetime, codecs, marshal, file, weakref, capsule, contextvars, thin clocks, process plumbing

Rule of thumb: prefer Core when the type is known; use Protocols only when it is not; use Runtime for non-hot-path / embedding needs.

Core (prefer for micro-opts)

Module	Maps to	Notes
cydict	dict	dict_get, dict_pop, dict_set, dict_len, …
cylist	list	list_append, list_get / list_get_checked, list_len, …
cytuple	tuple	tuple_get, tuple_len, tuple_pack*
cyset	set / frozenset	set_add, set_contains, …
cybytes / cybytearray	bytes / bytearray	len / eq / contains / startswith / …
cystr / cyunicode	str value ops / UTF-8 intern	Prefer cystr for value ops
cyansi	terminal SGR	Not CPython; builds on unicode intern
cygc	GC	gc_collect, gc_is_enabled, …
cyarray / cymemoryview / cybuffer / cyslice	buffers / slice	Core-adjacent

Curated starter export: picop.hot.

1.0 freeze (Core + cimport contracts)

As of 1.0.0:

Surface	Frozen?	Contract
picop.__all__	Yes	Core star-import / discovery set — additive in minors; drop/rename/semantic change → major
picop.hot.__all__	Yes	Micro-opt marketing set — same policy
Full public barrel beyond __all__	Protocols/Runtime provisional	Still importable; may evolve under minors
cimport picop / from picop.cy* cimport …	Documented SDK	Wider than Python; cimport-only helpers stay out of this Python API reference
Soft letter/bare/*_string (post-0.3)	Implementation only	Prefer word-prefix / *_cstr
Deprecated cypy import / cimport	Soft alias	Prefer picop; removed in 3.0

Protocols (typed unknown)

Module	Prefer instead when typed
cymapping	cydict
cysequence	cylist / cytuple
cynumber	cylong / cyfloat / cycomplex / cybool
cyobject	typed module above

Runtime (public and/or cimport)

Public Runtime helpers include datetime, codecs, marshal, file, weakref, capsule, contextvars, cytime clocks, and object-model / scalar modules (cyfunction, cymethod, cylong, …). Embedding / process helpers such as cyerr, cymem, cythread are cimport only and are not documented here as Python callables.

Import surfaces

Entry	Role
from picop.hot import …	Core marketing surface — micro-opt starters
import picop / from picop import …	Full public barrel; Core discovery via __all__
from picop.cydict import dict_get	Module-scoped public
cimport picop / from picop.cydict cimport …	Full Cython SDK (wider than Python)
from cypy…	Deprecated soft alias until 3.0

Discourage from picop import *.

Overlap decision tree

Known concrete type?
  dict  → cydict (dict_get, dict_len, …)
  list  → cylist
  tuple → cytuple
  set   → cyset
  bytes → cybytes
  str   → cystr value ops; encode/intern → cyunicode
Unknown mapping / sequence / number-like?
  → cymapping / cysequence / cynumber
Still too dynamic?
  → cyobject (last resort)

Not a goal

• Full Cython cpython.* parity or full Python stdlib

• Documenting every cimport / cdef symbol in the public Python API

• Treating Protocol/Runtime losers as Core micro-opt defaults