kubex-core 0.1.0a1__tar.gz

kubex_core-0.1.0a1/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+uv.lock
+.python-version
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+*.code-workspace
+.vscode/
+
+# Ruff
+.ruff_cache/
+scratches/

kubex_core-0.1.0a1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: kubex-core
+Version: 0.1.0a1
+Summary: Core model types shared by Kubex and its generated resource packages
+Author-email: Codemageddon <dev@codemageddon.me>
+License: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyyaml>=6.0.2
+Description-Content-Type: text/markdown
+
+# kubex-core
+
+Shared foundation types for [Kubex](https://github.com/codemageddon/kubex) and its generated Kubernetes resource packages (`kubex-k8s-*`).
+
+Contains:
+
+- `kubex_core.models.base.BaseK8sModel` — Pydantic base with camelCase aliasing.
+- `kubex_core.models.base_entity.BaseEntity` — base class for all K8s resources.
+- `kubex_core.models.interfaces` — marker interfaces (`NamespaceScopedEntity`, `ClusterScopedEntity`, `HasLogs`, `HasStatusSubresource`, `HasScaleSubresource`, `Evictable`).
+- `kubex_core.models.resource_config` — `ResourceConfig` descriptor + `Scope`.
+- `kubex_core.models.metadata` — `ObjectMetadata`, `ListMetadata`, `OwnerReference`.
+- `kubex_core.models.watch_event`, `list_entity`, `partial_object_meta`, `status`, `scale`.
+
+This package is a runtime dependency of the `kubex` client and every generated resource package. End users generally install `kubex` + one `kubex-k8s-*` of choice; this package is pulled in transitively.

kubex_core-0.1.0a1/README.md

@@ -0,0 +1,14 @@
+# kubex-core
+
+Shared foundation types for [Kubex](https://github.com/codemageddon/kubex) and its generated Kubernetes resource packages (`kubex-k8s-*`).
+
+Contains:
+
+- `kubex_core.models.base.BaseK8sModel` — Pydantic base with camelCase aliasing.
+- `kubex_core.models.base_entity.BaseEntity` — base class for all K8s resources.
+- `kubex_core.models.interfaces` — marker interfaces (`NamespaceScopedEntity`, `ClusterScopedEntity`, `HasLogs`, `HasStatusSubresource`, `HasScaleSubresource`, `Evictable`).
+- `kubex_core.models.resource_config` — `ResourceConfig` descriptor + `Scope`.
+- `kubex_core.models.metadata` — `ObjectMetadata`, `ListMetadata`, `OwnerReference`.
+- `kubex_core.models.watch_event`, `list_entity`, `partial_object_meta`, `status`, `scale`.
+
+This package is a runtime dependency of the `kubex` client and every generated resource package. End users generally install `kubex` + one `kubex-k8s-*` of choice; this package is pulled in transitively.

kubex_core-0.1.0a1/kubex_core/models/base.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class BaseK8sModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)

kubex_core-0.1.0a1/kubex_core/models/base_entity.py

@@ -0,0 +1,15 @@
+from typing import ClassVar, Self
+
+from kubex_core.models.base import BaseK8sModel
+from kubex_core.models.metadata import ObjectMetadata
+from kubex_core.models.resource_config import ResourceConfig
+
+
+class BaseEntity(BaseK8sModel):
+    """BaseEntity is the common fields for all entities."""
+
+    __RESOURCE_CONFIG__: ClassVar[ResourceConfig[Self]] = ResourceConfig()
+
+    api_version: str | None = None
+    kind: str | None = None
+    metadata: ObjectMetadata

kubex_core-0.1.0a1/kubex_core/models/interfaces.py

@@ -0,0 +1,19 @@
+from kubex_core.models.base_entity import BaseEntity
+
+
+class ClusterScopedEntity(BaseEntity): ...
+
+
+class NamespaceScopedEntity(BaseEntity): ...
+
+
+class HasStatusSubresource(BaseEntity): ...
+
+
+class HasScaleSubresource(BaseEntity): ...
+
+
+class HasLogs(BaseEntity): ...
+
+
+class Evictable(BaseEntity): ...

kubex_core-0.1.0a1/kubex_core/models/list_entity.py

@@ -0,0 +1,14 @@
+from typing import Generic
+
+from kubex_core.models.base import BaseK8sModel
+from kubex_core.models.metadata import ListMetadata
+from kubex_core.models.typing import ResourceType
+
+
+class ListEntity(BaseK8sModel, Generic[ResourceType]):
+    """ListEntity is the common fields for all list entities."""
+
+    api_version: str
+    kind: str
+    metadata: ListMetadata
+    items: list[ResourceType]

kubex_core-0.1.0a1/kubex_core/models/metadata.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import datetime
+
+from pydantic import Field
+
+from kubex_core.models.base import BaseK8sModel
+
+
+class OwnerReference(BaseK8sModel):
+    """OwnerReference contains enough information to let you identify an owning object."""
+
+    api_version: str
+    kind: str
+    name: str
+    uid: str
+    controller: bool | None = None
+    block_owner_deletion: bool | None = None
+
+
+class ObjectMetadata(BaseK8sModel):
+    """CommonMetadata is the common metadata for all Kubernetes API objects."""
+
+    labels: dict[str, str] | None = None
+    annotations: dict[str, str] | None = None
+    finalizers: list[str] | None = None
+    creation_timestamp: datetime.datetime | None = None
+    deletion_timestamp: datetime.datetime | None = None
+    deletion_grace_period_seconds: int | None = None
+    generation: int | None = None
+    resource_version: str | None = None
+    uid: str | None = None
+    name: str | None = None
+    namespace: str | None = None
+    generate_name: str | None = None
+    owner_references: list[OwnerReference] | None = None
+
+
+class ListMetadata(BaseK8sModel):
+    """ListMeta describes metadata that synthetic resources must have, including lists and various status objects."""
+
+    continue_: str | None = Field(None, alias="continue")
+    remaining_item_count: int | None = None
+    resource_version: str | None = None
+    self_link: str | None = None

kubex_core-0.1.0a1/kubex_core/models/partial_object_meta.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from kubex_core.models.base_entity import BaseEntity
+from kubex_core.models.metadata import ObjectMetadata
+
+
+class PartialObjectMetadata(BaseEntity):
+    """PartialObjectMetadata is the common metadata for all Kubernetes API objects."""
+
+    api_version: Literal["meta.k8s.io/v1"] = "meta.k8s.io/v1"
+    kind: Literal["PartialObjectMetadata"] = "PartialObjectMetadata"
+    metadata: ObjectMetadata

kubex_core-0.1.0a1/kubex_core/models/resource_config.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from enum import Enum
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Generic, Literal, Self, Type, cast
+
+from pydantic import create_model
+
+from kubex_core.models.typing import ResourceType
+
+if TYPE_CHECKING:
+    from kubex_core.models.list_entity import ListEntity
+
+
+class Scope(Enum):
+    CLUSTER = "cluster"
+    NAMESPACE = "namespace"
+
+
+class ResourceConfig(Generic[ResourceType]):
+    """ResourceConfig is the configuration for a resource."""
+
+    def __init__(
+        self,
+        version: str | None = None,
+        kind: str | None = None,
+        plural: str | None = None,
+        scope: Scope | None = None,
+        group: str | None = None,
+        list_model: Type[ListEntity[ResourceType]] | None = None,
+    ) -> None:
+        self._version = version
+        self._kind = kind
+        self._plural = plural
+        self._scope = scope
+        self._group = group
+        self._list_model = list_model
+
+    def __get__(self, instance: Any, owner: Type[ResourceType]) -> Self:
+        """Fill in the missing values from the owner."""
+        if kind_field := owner.model_fields.get("kind"):
+            if kind_field.default is not None:
+                self._kind = kind_field.default
+            else:
+                return self
+        if self._version is None or self._group is None:
+            if api_version_field := owner.model_fields.get("api_version"):
+                if api_version_field.default is not None:
+                    self._version, self._group = get_version_and_froup_from_api_version(
+                        api_version_field.default
+                    )
+            else:
+                return self
+        if self._list_model is None:
+            self._list_model = create_list_model(owner, self)
+        if self._scope is None:
+            self._scope = Scope.NAMESPACE
+        if self._plural is None:
+            if self._kind is None:
+                raise ValueError("kind is not set")
+            if self._kind.endswith("y"):
+                self._plural = f"{self._kind[:-1].lower()}ies"
+            elif self._kind.endswith("s") or self._kind.endswith("x"):
+                self._plural = f"{self._kind.lower()}es"
+            else:
+                self._plural = f"{self._kind.lower()}s"
+        return self
+
+    @property
+    def version(self) -> str:
+        if self._version is None:
+            raise ValueError("version is not set")
+        return self._version
+
+    @property
+    def kind(self) -> str:
+        if self._kind is None:
+            raise ValueError("kind is not set")
+        return self._kind
+
+    @property
+    def plural(self) -> str:
+        if self._plural is None:
+            raise ValueError("plural is not set")
+        return self._plural
+
+    @property
+    def scope(self) -> Scope:
+        if self._scope is None:
+            raise ValueError("scope is not set")
+        return self._scope
+
+    @property
+    def group(self) -> str:
+        if self._group is None:
+            raise ValueError("group is not set")
+        return self._group
+
+    @property
+    def list_model(self) -> Type[ListEntity[ResourceType]]:
+        if self._list_model is None:
+            raise ValueError("list_model is not set")
+        return self._list_model
+
+    def url(self, namespace: str | None = None, name: str | None = None) -> str:
+        """url returns the URL for the resource."""
+        if self.group and self.group != "core":
+            api_version = f"/apis/{self.group}/{self.version}"
+        else:
+            api_version = f"/api/{self.version}"
+
+        url: str
+        if namespace is None:
+            url = f"{api_version}/{self.plural}"
+        elif self.scope == Scope.CLUSTER:
+            raise ValueError("resource is cluster-scoped but namespace is set")
+        else:
+            url = f"{api_version}/namespaces/{namespace}/{self.plural}"
+
+        if name is None:
+            return url
+        return f"{url}/{name}"
+
+    @cached_property
+    def api_version(self) -> str:
+        if self.group and self.group != "core":
+            return f"{self.group}/{self.version}"
+        return self.version
+
+
+def create_list_model(
+    single_model: Type[ResourceType], resource_config: ResourceConfig[ResourceType]
+) -> Type[ListEntity[ResourceType]]:
+    from kubex_core.models.list_entity import ListEntity
+    from kubex_core.models.metadata import ListMetadata
+
+    kind = f"{resource_config.kind}List"
+    list_model = create_model(
+        kind,
+        api_version=(Literal[resource_config.api_version], resource_config.api_version),
+        kind=(Literal[kind], kind),
+        metadata=(ListMetadata, ...),
+        items=(list[single_model], ...),  # type: ignore[valid-type]
+        __base__=ListEntity[single_model],  # type: ignore[valid-type]
+    )
+    # pydantic.create_model's return type is `type[BaseModel]`; we know the
+    # __base__ narrows it to ListEntity[ResourceType], but mypy cannot prove it.
+    return cast("Type[ListEntity[ResourceType]]", list_model)
+
+
+def get_version_and_froup_from_api_version(api_version: str | None) -> tuple[str, str]:
+    """get_version_and_group_from_api_version returns the version and group from the apiVersion."""
+    if api_version is None:
+        raise ValueError("api_version is not set")
+    parts = api_version.split("/")
+    if len(parts) == 1:
+        return parts[0], "core"
+    return parts[1], parts[0]

kubex_core-0.1.0a1/kubex_core/models/scale.py

@@ -0,0 +1,22 @@
+from typing import Literal
+
+from .base import BaseK8sModel
+from .base_entity import BaseEntity
+from .metadata import ObjectMetadata
+
+
+class ScaleSpec(BaseK8sModel):
+    replicas: int
+
+
+class ScaleStatus(BaseK8sModel):
+    replicas: int
+    selector: str | None = None
+
+
+class Scale(BaseEntity):
+    api_version: Literal["autoscaling/v1"] = "autoscaling/v1"
+    kind: Literal["Scale"] = "Scale"
+    metadata: ObjectMetadata
+    spec: ScaleSpec
+    status: dict[str, int] | None = None

kubex_core-0.1.0a1/kubex_core/models/status.py

@@ -0,0 +1,60 @@
+from typing import Literal
+
+from .base import BaseK8sModel
+from .base_entity import BaseEntity
+from .resource_config import ResourceConfig, Scope
+
+
+class StatusCause(BaseK8sModel):
+    """StatusCause provides more information about an api.Status failure, including cases when multiple errors are encountered."""
+
+    message: str
+    """A human-readable description of the cause of the error. This field may be presented as-is to a reader."""
+    field: str | None = None
+    """The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional. Examples: "name" - the field "name" on the current resource "items[0].name" - the field "name" on the first array entry in \"items\"
+    """
+    reason: str | None = None
+    """A machine-readable description of the cause of the error. If this value is empty there is no information available."""
+
+
+class StatusDetails(BaseK8sModel):
+    """tatusDetails is a set of additional properties that MAY be set by the server to provide additional information about a response. The Reason field of a Status object defines what attributes will be set. Clients must ignore fields that do not match the defined type of each attribute, and should assume that any attribute may be empty, invalid, or under defined."""
+
+    causes: list[StatusCause] | None = None
+    """The Causes array includes more details associated with the StatusReason failure. Not all StatusReasons may provide detailed causes."""
+    name: str | None = None
+    """The name attribute of the resource associated with the status StatusReason (when there is a single name which can be described)."""
+    group: str | None = None
+    """The group attribute of the resource associated with the status StatusReason."""
+    kind: str | None = None
+    """The kind attribute of the resource associated with the status StatusReason. On some operations may differ from the requested resource Kind. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds"""
+    retry_after_seconds: int | None = None
+    """If specified, the time in seconds before the operation should be retried. Some errors may indicate the client must take an alternate action - for those errors this field may indicate how long to wait before taking the alternate action."""
+    uid: str | None = None
+    """UID of the resource. (when there is a single resource which can be described). More info: http://kubernetes.io/docs/user-guide/identifiers#uids"""
+
+
+class Status(BaseEntity):
+    """Status is a return value for calls that don't return other objects."""
+
+    api_version: Literal["meta/v1"] | None = "meta/v1"
+    """APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources"""
+    kind: Literal["Status"] | None = "Status"
+    """Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds"""
+    code: int = 0
+    """Suggested HTTP return code for this status, 0 if not set."""
+    details: StatusDetails | None = None
+    """Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type."""
+    message: str | None = None
+    """A human-readable description of the status of this operation."""
+    reason: str | None = None
+    """A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. A Reason clarifies an HTTP status code but does not override it."""
+    status: Literal["Success", "Failure"]
+    """Status of the operation. One of: "Success" or "Failure". More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status"""
+
+    __RESOURCE_CONFIG__ = ResourceConfig["Status"](
+        version="meta/v1",
+        kind="Status",
+        plural="statuses",
+        scope=Scope.CLUSTER,
+    )

kubex_core-0.1.0a1/kubex_core/models/typing.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from kubex_core.models.base_entity import BaseEntity  # noqa: F401
+
+
+ResourceType = TypeVar("ResourceType", bound="BaseEntity")

kubex_core-0.1.0a1/kubex_core/models/watch_event.py

@@ -0,0 +1,36 @@
+from enum import Enum
+from typing import Any, Generic, Type
+
+from .base_entity import BaseEntity
+from .typing import ResourceType
+
+
+class EventType(str, Enum):
+    """EventType is the type of the watch event."""
+
+    ADDED = "ADDED"
+    MODIFIED = "MODIFIED"
+    DELETED = "DELETED"
+    BOOKMARK = "BOOKMARK"
+
+
+class Bookmark(BaseEntity):
+    """Bookmark is a pointer to a resource in a stream."""
+
+
+class WatchEvent(Generic[ResourceType]):
+    """WatchEvent represents a single event from a watch stream."""
+
+    def __init__(
+        self, resource_type: Type[ResourceType], raw_event: dict[str, Any]
+    ) -> None:
+        self._resource_type = resource_type
+        self.type = EventType(raw_event["type"])
+        self.object: ResourceType | Bookmark
+        if self.type == EventType.BOOKMARK:
+            self.object = Bookmark.model_validate(raw_event["object"])
+        else:
+            self.object = self._resource_type.model_validate(raw_event["object"])
+
+    def __repr__(self) -> str:
+        return f"WatchEvent(type={self.type}, object={self.object})"

kubex_core-0.1.0a1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "kubex-core"
+version = "0.1.0-alpha.1"
+description = "Core model types shared by Kubex and its generated resource packages"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT License"}
+authors = [
+    {name = "Codemageddon", email = "dev@codemageddon.me"},
+]
+dependencies = [
+    "pydantic>=2.0,<3",
+    "pyyaml>=6.0.2",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["kubex_core"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["kubex_core"]