kindof 0.1.0__tar.gz

kindof-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: kindof
+Version: 0.1.0
+Summary: Typed, JSON-compatible object inspection for Python.
+Author: wispsy
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kindof
+
+`kindof` provides a small, typed API for describing Python objects at runtime.
+It is useful when an application needs stable metadata or a JSON-compatible
+description without serializing an object's values directly.
+
+```python
+from kindof import inspect
+
+description = inspect(instance)
+print(description.schema)
+```
+
+The result exposes `type`, `fields`, `methods`, `signatures`, `annotations`, and
+a recursive JSON-compatible `schema`. Instance fields, class fields,
+properties, inherited members, and safely introspectable method signatures are
+included. Unsupported or dynamic members are omitted.
+
+## Installation
+
+```shell
+python -m pip install kindof
+```
+
+## Quick example
+
+```python
+from kindof import inspect
+
+
+class User:
+    name: str
+    active: bool = True
+
+    def greet(self, punctuation: str = "!") -> str:
+        return f"{self.name}{punctuation}"
+
+
+user = User()
+user.name = "Ada"
+result = inspect(user)
+
+assert result.fields["name"].required is False
+assert result.methods["greet"].signature == "(self, punctuation: str = '!') -> str"
+assert result.schema["properties"]["name"] == {"type": "string"}
+```
+
+See [the API guide](docs/api.md) for the complete result model and schema
+mapping, and [the examples](docs/examples.md) for more usage patterns.
+
+## Releasing
+
+Releases are published to PyPI through GitHub Actions using trusted publishing.
+The repository's `pypi` environment supplies the OIDC authorization; no PyPI
+token is stored in the repository. To publish a release:
+
+1. Confirm the version in `pyproject.toml`.
+2. Create and publish a GitHub release whose tag is exactly `v<version>` (for
+   example, `v0.1.0`).
+3. The release workflow checks the tag against the package metadata, builds and
+   validates the source distribution and wheel, and publishes both to PyPI.

kindof-0.1.0/README.md

@@ -0,0 +1,61 @@
+# kindof
+
+`kindof` provides a small, typed API for describing Python objects at runtime.
+It is useful when an application needs stable metadata or a JSON-compatible
+description without serializing an object's values directly.
+
+```python
+from kindof import inspect
+
+description = inspect(instance)
+print(description.schema)
+```
+
+The result exposes `type`, `fields`, `methods`, `signatures`, `annotations`, and
+a recursive JSON-compatible `schema`. Instance fields, class fields,
+properties, inherited members, and safely introspectable method signatures are
+included. Unsupported or dynamic members are omitted.
+
+## Installation
+
+```shell
+python -m pip install kindof
+```
+
+## Quick example
+
+```python
+from kindof import inspect
+
+
+class User:
+    name: str
+    active: bool = True
+
+    def greet(self, punctuation: str = "!") -> str:
+        return f"{self.name}{punctuation}"
+
+
+user = User()
+user.name = "Ada"
+result = inspect(user)
+
+assert result.fields["name"].required is False
+assert result.methods["greet"].signature == "(self, punctuation: str = '!') -> str"
+assert result.schema["properties"]["name"] == {"type": "string"}
+```
+
+See [the API guide](docs/api.md) for the complete result model and schema
+mapping, and [the examples](docs/examples.md) for more usage patterns.
+
+## Releasing
+
+Releases are published to PyPI through GitHub Actions using trusted publishing.
+The repository's `pypi` environment supplies the OIDC authorization; no PyPI
+token is stored in the repository. To publish a release:
+
+1. Confirm the version in `pyproject.toml`.
+2. Create and publish a GitHub release whose tag is exactly `v<version>` (for
+   example, `v0.1.0`).
+3. The release workflow checks the tag against the package metadata, builds and
+   validates the source distribution and wheel, and publishes both to PyPI.

kindof-0.1.0/kindof/__init__.py

@@ -0,0 +1,5 @@
+"""Public API for inspecting Python objects."""
+
+from .inspection import FieldInfo, InspectionResult, MethodInfo, inspect
+
+__all__ = ["FieldInfo", "InspectionResult", "MethodInfo", "inspect"]

kindof-0.1.0/kindof/inspection.py

@@ -0,0 +1,233 @@
+"""Runtime object inspection with a stable, JSON-compatible result."""
+
+from __future__ import annotations
+
+import inspect as _inspect
+import json
+import types
+import typing
+from dataclasses import dataclass, field
+from typing import Any
+
+_UNION_TYPE = getattr(types, "UnionType", None)
+
+
+def _type_name(value: Any) -> str:
+    if value is Any:
+        return "Any"
+    if isinstance(value, str):
+        return value
+    origin = typing.get_origin(value)
+    if origin is typing.Union or (
+        _UNION_TYPE is not None and origin is _UNION_TYPE
+    ):
+        return " | ".join(_type_name(item) for item in typing.get_args(value))
+    if origin is not None:
+        name = getattr(origin, "__name__", str(origin))
+        args = ", ".join(_type_name(item) for item in typing.get_args(value))
+        return f"{name}[{args}]" if args else name
+    return getattr(value, "__qualname__", getattr(value, "__name__", str(value)))
+
+
+def _json_value(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    try:
+        json.dumps(value)
+    except (TypeError, ValueError):
+        return repr(value)
+    return value
+
+
+def _safe_annotations(cls: type[Any]) -> dict[str, Any]:
+    try:
+        return dict(typing.get_type_hints(cls))
+    except (NameError, TypeError, ValueError):
+        annotations: dict[str, Any] = {}
+        for base in reversed(cls.__mro__):
+            annotations.update(getattr(base, "__annotations__", {}))
+        return annotations
+
+
+def _safe_signature(member: Any) -> str | None:
+    try:
+        return str(_inspect.signature(member))
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass(frozen=True)
+class FieldInfo:
+    """Description of an inspectable field."""
+
+    name: str
+    type: str
+    default: Any = None
+    required: bool = False
+    kind: str = "field"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "type": self.type,
+            "default": _json_value(self.default),
+            "required": self.required,
+            "kind": self.kind,
+        }
+
+
+@dataclass(frozen=True)
+class MethodInfo:
+    """Description of an inspectable method."""
+
+    name: str
+    signature: str | None
+    annotations: dict[str, str] = field(default_factory=dict)
+    kind: str = "method"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "signature": self.signature,
+            "annotations": dict(self.annotations),
+            "kind": self.kind,
+        }
+
+
+@dataclass(frozen=True)
+class InspectionResult:
+    """Structured inspection data returned by :func:`inspect`."""
+
+    type: str
+    fields: dict[str, FieldInfo]
+    methods: dict[str, MethodInfo]
+    signatures: dict[str, str]
+    annotations: dict[str, str]
+    schema: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a recursively JSON-compatible representation."""
+        return {
+            "type": self.type,
+            "fields": {name: value.to_dict() for name, value in self.fields.items()},
+            "methods": {name: value.to_dict() for name, value in self.methods.items()},
+            "signatures": dict(self.signatures),
+            "annotations": dict(self.annotations),
+            "schema": self.schema,
+        }
+
+
+def _schema_for(annotation: Any) -> dict[str, Any]:
+    origin = typing.get_origin(annotation)
+    args = typing.get_args(annotation)
+    if annotation is Any:
+        return {}
+    if origin is typing.Union or (
+        _UNION_TYPE is not None and origin is _UNION_TYPE
+    ):
+        non_none = [item for item in args if item is not type(None)]
+        if len(non_none) != len(args):
+            return _schema_for(non_none[0]) if len(non_none) == 1 else {
+                "anyOf": [_schema_for(item) for item in non_none]
+            }
+        return {"anyOf": [_schema_for(item) for item in args]}
+    if origin in (list, tuple, set, frozenset):
+        return {"type": "array", "items": _schema_for(args[0]) if args else {}}
+    if origin is dict:
+        return {"type": "object"}
+    primitive = {str: "string", int: "integer", float: "number", bool: "boolean"}
+    if annotation in primitive:
+        return {"type": primitive[annotation]}
+    return {"type": "object"}
+
+
+def inspect(obj: Any) -> InspectionResult:
+    """Inspect an object or class and return stable metadata."""
+    cls = obj if _inspect.isclass(obj) else type(obj)
+    annotations = _safe_annotations(cls)
+    values = (
+        {}
+        if _inspect.isclass(obj)
+        else vars(obj)
+        if hasattr(obj, "__dict__")
+        else {}
+    )
+    fields: dict[str, FieldInfo] = {}
+
+    for name, annotation in annotations.items():
+        class_member = getattr(cls, name, None)
+        if callable(class_member):
+            continue
+        member = getattr(obj, name, class_member)
+        has_class_default = (
+            name in cls.__dict__
+            and not isinstance(class_member, types.MemberDescriptorType)
+            and not isinstance(class_member, property)
+        )
+        has_default = name in values or has_class_default
+        fields[name] = FieldInfo(
+            name=name,
+            type=_type_name(annotation),
+            default=values.get(name, member),
+            required=not has_default,
+            kind="property" if isinstance(class_member, property) else "field",
+        )
+
+    for name, value in values.items():
+        if name.startswith("_") or name in fields or callable(value):
+            continue
+        fields[name] = FieldInfo(name, _type_name(type(value)), value)
+
+    for name, member in _inspect.getmembers(cls):
+        if name.startswith("_") or name in fields:
+            continue
+        if isinstance(member, property):
+            fields[name] = FieldInfo(
+                name,
+                _type_name(annotations.get(name, Any)),
+                kind="property",
+            )
+
+    methods: dict[str, MethodInfo] = {}
+    signatures: dict[str, str] = {}
+    for name, member in _inspect.getmembers(cls, callable):
+        if name.startswith("_"):
+            continue
+        signature = _safe_signature(member)
+        if signature is None:
+            continue
+        try:
+            method_annotations = {
+                key: _type_name(value)
+                for key, value in typing.get_type_hints(member).items()
+            }
+        except (NameError, TypeError, ValueError):
+            method_annotations = {}
+        descriptor = cls.__dict__.get(name)
+        kind = "classmethod" if isinstance(descriptor, classmethod) else "method"
+        methods[name] = MethodInfo(name, signature, method_annotations, kind)
+        signatures[name] = signature
+
+    schema_properties = {
+        name: _schema_for(
+            annotations.get(name, type(values[name]) if name in values else Any)
+        )
+        for name in fields
+    }
+    schema: dict[str, Any] = {
+        "type": "object",
+        "title": cls.__name__,
+        "properties": schema_properties,
+    }
+    required = [name for name, info in fields.items() if info.required]
+    if required:
+        schema["required"] = required
+
+    return InspectionResult(
+        type=f"{cls.__module__}.{cls.__qualname__}",
+        fields=fields,
+        methods=methods,
+        signatures=signatures,
+        annotations={name: _type_name(value) for name, value in annotations.items()},
+        schema=schema,
+    )

kindof-0.1.0/kindof.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: kindof
+Version: 0.1.0
+Summary: Typed, JSON-compatible object inspection for Python.
+Author: wispsy
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kindof
+
+`kindof` provides a small, typed API for describing Python objects at runtime.
+It is useful when an application needs stable metadata or a JSON-compatible
+description without serializing an object's values directly.
+
+```python
+from kindof import inspect
+
+description = inspect(instance)
+print(description.schema)
+```
+
+The result exposes `type`, `fields`, `methods`, `signatures`, `annotations`, and
+a recursive JSON-compatible `schema`. Instance fields, class fields,
+properties, inherited members, and safely introspectable method signatures are
+included. Unsupported or dynamic members are omitted.
+
+## Installation
+
+```shell
+python -m pip install kindof
+```
+
+## Quick example
+
+```python
+from kindof import inspect
+
+
+class User:
+    name: str
+    active: bool = True
+
+    def greet(self, punctuation: str = "!") -> str:
+        return f"{self.name}{punctuation}"
+
+
+user = User()
+user.name = "Ada"
+result = inspect(user)
+
+assert result.fields["name"].required is False
+assert result.methods["greet"].signature == "(self, punctuation: str = '!') -> str"
+assert result.schema["properties"]["name"] == {"type": "string"}
+```
+
+See [the API guide](docs/api.md) for the complete result model and schema
+mapping, and [the examples](docs/examples.md) for more usage patterns.
+
+## Releasing
+
+Releases are published to PyPI through GitHub Actions using trusted publishing.
+The repository's `pypi` environment supplies the OIDC authorization; no PyPI
+token is stored in the repository. To publish a release:
+
+1. Confirm the version in `pyproject.toml`.
+2. Create and publish a GitHub release whose tag is exactly `v<version>` (for
+   example, `v0.1.0`).
+3. The release workflow checks the tag against the package metadata, builds and
+   validates the source distribution and wheel, and publishes both to PyPI.

kindof-0.1.0/kindof.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+kindof/__init__.py
+kindof/inspection.py
+kindof.egg-info/PKG-INFO
+kindof.egg-info/SOURCES.txt
+kindof.egg-info/dependency_links.txt
+kindof.egg-info/top_level.txt
+tests/test_inspection.py

kindof-0.1.0/kindof.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kindof-0.1.0/kindof.egg-info/top_level.txt

@@ -0,0 +1 @@
+kindof

kindof-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kindof"
+version = "0.1.0"
+description = "Typed, JSON-compatible object inspection for Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "wispsy"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[tool.setuptools.packages.find]
+include = ["kindof*"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

kindof-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kindof-0.1.0/tests/test_inspection.py

@@ -0,0 +1,134 @@
+import json
+from typing import Any, Optional, Union
+
+from kindof import inspect
+
+
+class Parent:
+    inherited: str = "parent"
+
+    def inherited_method(self, value: int) -> str:
+        return str(value)
+
+
+class User(Parent):
+    name: str
+    age: int = 0
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    @property
+    def display_name(self) -> str:
+        return self.name.upper()
+
+    def greet(self, punctuation: Optional[str] = None) -> str:
+        return self.name + (punctuation or "!")
+
+
+class Complex:
+    text: str
+    values: list[int]
+    mapping: dict[str, int]
+    maybe: Optional[str]
+    choice: Union[int, str]
+    unknown: Any
+
+    @classmethod
+    def make(cls, value: int) -> "Complex":
+        return cls()
+
+
+class WithSlots:
+    __slots__ = ("value",)
+    value: int
+
+
+def test_inspect_collects_fields_methods_and_inheritance() -> None:
+    result = inspect(User("Ada"))
+
+    assert result.type.endswith(".User")
+    assert set(result.fields) >= {"name", "age", "inherited", "display_name"}
+    assert set(result.methods) >= {"greet", "inherited_method"}
+    assert (
+        result.signatures["greet"]
+        == "(self, punctuation: Optional[str] = None) -> str"
+    )
+    assert result.fields["display_name"].kind == "property"
+    assert result.annotations["name"] == "str"
+    assert result.fields["name"].required is False
+    assert result.fields["inherited"].default == "parent"
+
+
+def test_inspecting_a_class_does_not_read_instance_values() -> None:
+    result = inspect(User)
+
+    assert result.fields["name"].required is True
+    assert result.fields["name"].default is None
+    assert result.fields["age"].default == 0
+
+
+def test_schema_and_to_dict_are_json_compatible() -> None:
+    payload = inspect(User).to_dict()
+
+    assert payload["schema"]["type"] == "object"
+    assert payload["schema"]["properties"]["name"] == {"type": "string"}
+    assert payload["schema"]["properties"]["age"] == {"type": "integer"}
+    assert payload["schema"]["properties"]["display_name"] == {}
+    json.dumps(payload)
+
+
+def test_schema_handles_recursive_containers_unions_and_any() -> None:
+    schema = inspect(Complex).schema
+
+    assert schema["properties"]["values"] == {
+        "type": "array",
+        "items": {"type": "integer"},
+    }
+    assert schema["properties"]["mapping"] == {"type": "object"}
+    assert schema["properties"]["maybe"] == {"type": "string"}
+    assert schema["properties"]["choice"] == {
+        "anyOf": [{"type": "integer"}, {"type": "string"}]
+    }
+    assert schema["properties"]["unknown"] == {}
+    assert set(schema["required"]) >= {
+        "text",
+        "values",
+        "mapping",
+        "maybe",
+        "choice",
+        "unknown",
+    }
+
+
+def test_method_metadata_includes_annotations_and_classmethod_kind() -> None:
+    result = inspect(Complex)
+
+    assert result.methods["make"].kind == "classmethod"
+    assert result.methods["make"].signature == "(value: int) -> 'Complex'"
+    assert result.methods["make"].annotations == {"value": "int", "return": "Complex"}
+    assert result.signatures["make"] == result.methods["make"].signature
+
+
+def test_slots_only_objects_are_safe_to_inspect() -> None:
+    result = inspect(WithSlots())
+
+    assert result.fields["value"].required is True
+    assert result.schema["properties"]["value"] == {"type": "integer"}
+
+
+def test_private_and_callable_instance_values_are_omitted() -> None:
+    class Dynamic:
+        visible: int = 1
+
+        def __init__(self) -> None:
+            self.extra = object()
+            self._private = "hidden"
+            self.callback = lambda: None
+
+    result = inspect(Dynamic())
+
+    assert "extra" in result.fields
+    assert "_private" not in result.fields
+    assert "callback" not in result.fields
+    assert isinstance(result.to_dict()["fields"]["extra"]["default"], str)