Overview

Relevant source files

• LICENSE
• README.md
• docs/assets/logo_1.svg
• docs/assets/logo_2.svg
• pyproject.toml
• simtypes/__init__.py

Purpose: This document provides a high-level introduction to the simtypes library, its architecture, core components, and design philosophy. For detailed usage instructions, see User Guide. For API specifications, see API Reference. For internal implementation details, see Architecture and Design.

What is simtypes?

simtypes is a Python library for runtime type validation and string deserialization. It is intentionally minimal — it excludes typing semantics meaningful only for static analysis and focuses on a small set of well-defined runtime checks.

Core features:

• Runtime type checking via check() — returns True/False for a value/type pair (simtypes/check.py)
• String deserialization via from_string() — converts strings into typed Python values, raises TypeError on failure (simtypes/from_string.py)
• Custom constrained integer types: NaturalNumber, NonNegativeInt (simtypes/types/ints/)
• Sentinel type integration: InnerNoneType from the denial library (pyproject.toml14)
• Python 3.8–3.14 support including free-threading builds (pyproject.toml23-30)

Sources: README.md1-56 pyproject.toml6-36 simtypes/__init__.py1-7

Library Structure

Package module layout and public exports

Sources: simtypes/__init__.py1-7 pyproject.toml12-15

Core Components

check()

Located in simtypes/check.py Accepts a value and a type annotation, returns True or False.

Parameter	Default	Description
value	—	The value to validate
annotation	—	A type or type annotation
strict	False	If True, validates contents of list, dict, tuple
pass_mocks	True	If True, mock objects always pass
lists_are_tuples	False	If True, lists are accepted where tuples are expected

Supported annotations:

• Basic types via isinstance(): int, str, float, etc.
• Union[X, Y] / X | Y
• Optional[X] (equivalent to Union[X, None])
• Any (always returns True)
• Generic collections: List[X], Dict[K, V], Tuple[X, ...]
• Custom types: NaturalNumber, NonNegativeInt, InnerNoneType

from_string()

Located in simtypes/from_string.py Converts a string to a typed Python value. Raises TypeError if conversion fails.

Supported target types:

Target type	Accepted string format
str	Any string
Any	Any string (returned as str)
int	Integer literal, e.g. "13", "-13"
float	Float literal, "nan", "inf", "∞", "-∞"
bool	"yes", "True", "true" → True; "no", "False", "false" → False
date	ISO 8601 date string, e.g. "2026-01-27"
datetime	ISO 8601 datetime string
list / list[X]	JSON array
tuple / tuple[X, ...]	JSON array
dict / dict[K, V]	JSON object

Sources: README.md70-253 simtypes/check.py simtypes/from_string.py

Custom Types

Custom type hierarchy and isinstance() extension pattern

Type	Location	Accepted values
NaturalNumber	simtypes/types/ints/natural.py	int > 0
NonNegativeInt	simtypes/types/ints/non_negative.py	int >= 0
InnerNoneType	denial library	Instances of InnerNoneType with matching key

Both NaturalNumber and NonNegativeInt use a metaclass with __instancecheck__ to extend how isinstance() behaves, making them usable transparently with check().

InnerNoneType is an extended sentinel from the denial library that distinguishes between "no value provided" and None. An instance of InnerNoneType can be used as its own type annotation in check().

Sources: README.md147-178 simtypes/__init__.py3-7

Data Flow Architecture

Type Checking Flow

Sources: simtypes/check.py Diagram 2 from architecture overview

String Deserialization Flow

Sources: simtypes/from_string.py Diagram 3 from architecture overview, README.md181-253

Design Philosophy

From README.md33-56 the library is built around one explicit goal: make type checking "as stupid as possible" to avoid the complexity imposed by comprehensive tools.

Simplicity Over Completeness

The library is intentionally scoped to the minimum useful set of runtime checks.

Supported:

Feature	Mode
isinstance() for basic types	Always
Union[X, Y] / Optional[X]	Always
Any annotation	Always (always True)
Collection base-type check	Default (strict=False)
Collection element validation	strict=True only
NaturalNumber, NonNegativeInt	Always
InnerNoneType sentinels	Always

Not supported:

• String annotations
• Literal, TypedDict, Protocol, Final, Callable, etc.
• Covariance / contravariance semantics

isinstance() as the Foundation

All non-generic type checks ultimately delegate to Python's built-in isinstance(). The custom types (NaturalNumber, NonNegativeInt) extend this by implementing __instancecheck__ on their metaclasses rather than patching the type system.

Non-strict by Default

In default mode, check([1, "x"], list[int]) returns True — the list content is not inspected. Deep validation requires strict=True and is opt-in because iterating all elements is expensive.

Minimal Dependencies

Dependency	Version	Purpose
denial	>= 0.0.5	InnerNoneType, sentinel types
typing_extensions	any	Backports for Python <= 3.12

All other functionality uses standard library modules: typing, json, datetime, unittest.mock.

Sources: README.md33-56 pyproject.toml12-15

When to Use simtypes

Appropriate use cases:

• Runtime validation where isinstance() is insufficient (e.g., constrained integers, sentinels)
• String-to-typed-value deserialization for basic types
• Building higher-level validation tools (decorators, validators) on top of check()

Not appropriate when:

• You need mypy-equivalent semantics at runtime
• You need string-annotated type hints
• You need Literal, Protocol, TypedDict, or similar constructs

Sources: README.md33-56

Quality Assurance

The library maintains high quality standards through:

• 100% code coverage requirement (pyproject.toml Diagram 4)
• Type checking with mypy --strict
• Linting with ruff
• Mutation testing with mutmut
• CI/CD across 24 configurations: 3 OS × 8 Python versions (3.8-3.14t)

For details on testing and development, see Development Guide.

Sources: Diagram 4 from architecture overview, pyproject.toml41-51