{"id":35458243,"url":"https://github.com/lzjever/serilux","last_synced_at":"2026-01-03T07:03:57.028Z","repository":{"id":330840159,"uuid":"1124129592","full_name":"lzjever/serilux","owner":"lzjever","description":"A powerful serialization framework for Python objects with automatic type registration and validation. Extract from AgentSmith, released under Apache 2.0.","archived":false,"fork":false,"pushed_at":"2025-12-30T17:41:49.000Z","size":95,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T23:21:15.826Z","etag":null,"topics":["configuration-management","deserialization","json","nested-objects","object-persistence","persistence","python","serializable","serialization","state-management","type-safety","validation","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://serilux.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lzjever.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T11:57:16.000Z","updated_at":"2025-12-30T17:41:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lzjever/serilux","commit_stats":null,"previous_names":["lzjever/serilux"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lzjever/serilux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzjever%2Fserilux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzjever%2Fserilux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzjever%2Fserilux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzjever%2Fserilux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lzjever","download_url":"https://codeload.github.com/lzjever/serilux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lzjever%2Fserilux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28184106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-03T02:00:06.471Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration-management","deserialization","json","nested-objects","object-persistence","persistence","python","serializable","serialization","state-management","type-safety","validation","zero-dependencies"],"created_at":"2026-01-03T07:03:31.992Z","updated_at":"2026-01-03T07:03:57.019Z","avatar_url":"https://github.com/lzjever.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serilux 📦\n\n[![PyPI version](https://img.shields.io/pypi/v/serilux.svg)](https://pypi.org/project/serilux/)\n[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)\n[![Documentation](https://readthedocs.org/projects/serilux/badge/?version=latest)](https://serilux.readthedocs.io)\n[![CI](https://github.com/lzjever/serilux/workflows/CI/badge.svg)](https://github.com/lzjever/serilux/actions)\n[![codecov](https://codecov.io/gh/lzjever/serilux/branch/main/graph/badge.svg)](https://codecov.io/gh/lzjever/serilux)\n\n**Serilux** is a powerful, flexible serialization framework for Python objects. With its intuitive API and automatic type registration, you can easily serialize and deserialize complex object hierarchies with minimal code.\n\n## ✨ Why Serilux?\n\n- 🎯 **Simple API**: Just inherit from `Serializable` and you're ready to go\n- 🔄 **Automatic Type Registration**: Classes are automatically registered for deserialization\n- 🛡️ **Type Safety**: Built-in validation ensures objects can be properly deserialized\n- 🌳 **Nested Objects**: Automatically handles nested Serializable objects, lists, and dictionaries\n- 🔧 **Callable Serialization**: Full support for serializing functions, methods, and lambda expressions\n- 🔒 **Security**: Strict mode prevents deserialization of unknown fields\n- ⚡ **Zero Dependencies**: Pure Python with no external dependencies\n- 🎓 **Easy to Use**: Minimal boilerplate, maximum flexibility\n\n## 🎯 Perfect For\n\n- **Object Persistence**: Save and restore complex object states\n- **Configuration Management**: Serialize configuration objects to JSON/YAML\n- **Data Transfer**: Convert objects to dictionaries for API communication\n- **State Management**: Save application state for recovery\n- **Workflow Orchestration**: Serialize workflow definitions and states\n- **Testing**: Create test fixtures from serialized objects\n\n## 📦 Installation\n\n### Quick Install (Recommended)\n\n```bash\npip install serilux\n```\n\nThat's it! You're ready to go.\n\n### Development Setup with uv (Recommended)\n\nThis project uses [uv](https://github.com/astral-sh/uv) for fast dependency management. Install uv first:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nThen set up the development environment:\n\n**Recommended: For active development**\n\n```bash\n# Install package with all development dependencies (recommended)\nmake dev-install\n\n# Or manually with uv (dev group is installed by default)\nuv sync --group docs --all-extras\n```\n\n**Alternative: Dependencies only (for CI/CD or code review)**\n\n```bash\n# Create virtual environment and install dependencies only (without installing the package)\n# Useful for: CI/CD pipelines, code review, or when you only need development tools\nmake setup-venv\n\n# Later, if you need to install the package:\nmake install\n```\n\n**Understanding dependency groups vs extras:**\n\n- **Dependency groups** (`dev`, `docs`): Development dependencies that are not published to PyPI. The `dev` group is installed by default with `uv sync`.\n- **Extras**: Currently none, but may be added in the future.\n\nAll `make` commands will automatically use `uv` if available, otherwise fall back to `pip`.\n\n### Development Install (Legacy - using pip)\n\nFor development with all dependencies using pip:\n\n```bash\npip install -e \".[dev]\"\n# Or using Makefile\nmake dev-install\n```\n\n## 🚀 Quick Start\n\n### Create Your First Serializable Class in 3 Steps\n\n**Step 1: Define a Serializable Class**\n\n```python\nfrom serilux import Serializable, register_serializable\n\n@register_serializable\nclass Person(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.name = \"\"\n        self.age = 0\n        # Register fields to serialize\n        self.add_serializable_fields([\"name\", \"age\"])\n```\n\n**Step 2: Create and Use Objects**\n\n```python\n# Create an object\nperson = Person()\nperson.name = \"Alice\"\nperson.age = 30\n\n# Serialize to dictionary\ndata = person.serialize()\nprint(data)\n# {'_type': 'Person', 'name': 'Alice', 'age': 30}\n```\n\n**Step 3: Deserialize**\n\n```python\n# Deserialize from dictionary\nnew_person = Person()\nnew_person.deserialize(data)\nprint(new_person.name)  # \"Alice\"\nprint(new_person.age)   # 30\n```\n\n**🎉 Done!** You've created your first serializable class.\n\n## 💡 Key Features\n\n### 🔄 Automatic Type Registration\n\nClasses decorated with `@register_serializable` are automatically registered:\n\n```python\n@register_serializable\nclass MyClass(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.add_serializable_fields([\"field1\", \"field2\"])\n```\n\n**Class Name Conflict Detection**: Serilux automatically detects and prevents class name conflicts.\nIf you try to register a different class with the same name, a `ValueError` is raised to prevent\nincorrect deserialization:\n\n```python\n@register_serializable\nclass Processor(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.name = \"\"\n        self.add_serializable_fields([\"name\"])\n\n# This will raise ValueError: Class name conflict\n@register_serializable\nclass Processor(Serializable):  # Different class, same name\n    def __init__(self):\n        super().__init__()\n        self.value = 0\n        self.add_serializable_fields([\"value\"])\n```\n\n### 🌳 Nested Objects\n\nAutomatically handles nested Serializable objects:\n\n```python\n@register_serializable\nclass Address(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.street = \"\"\n        self.city = \"\"\n        self.add_serializable_fields([\"street\", \"city\"])\n\n@register_serializable\nclass Person(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.name = \"\"\n        self.address = None\n        self.add_serializable_fields([\"name\", \"address\"])\n\n# Create nested objects\nperson = Person()\nperson.name = \"Alice\"\nperson.address = Address()\nperson.address.street = \"123 Main St\"\nperson.address.city = \"New York\"\n\n# Serialize - nested objects are automatically handled\ndata = person.serialize()\n```\n\n### 📋 Lists and Dictionaries\n\nHandles lists and dictionaries containing Serializable objects:\n\n```python\n@register_serializable\nclass Team(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.name = \"\"\n        self.members = []  # List of Person objects\n        self.add_serializable_fields([\"name\", \"members\"])\n\nteam = Team()\nteam.name = \"Engineering\"\nteam.members = [person1, person2, person3]\n\n# Serialize - list items are automatically serialized\ndata = team.serialize()\n```\n\n### 🔧 Callable Serialization\n\nSerilux supports serializing and deserializing callable objects (functions, methods, lambda expressions):\n\n```python\nfrom serilux import serialize_callable, deserialize_callable, serialize_callable_with_fallback\n\n# Serialize a function\ndef process_data(data):\n    return data.upper()\n\nserialized = serialize_callable(process_data)\nrestored = deserialize_callable(serialized)\nresult = restored(\"hello\")  # Returns \"HELLO\"\n\n# Serialize lambda expression\ncondition = lambda x: x.get(\"priority\") == \"high\"\nserialized_lambda = serialize_callable_with_fallback(condition)\n# Returns: {\"_type\": \"lambda_expression\", \"expression\": \"x.get('priority') == 'high'\"}\n```\n\nCallable fields in Serializable objects are automatically serialized:\n\n```python\n@register_serializable\nclass Processor(Serializable):\n    def __init__(self):\n        super().__init__()\n        self.handler = None  # Will store a function\n        self.add_serializable_fields([\"handler\"])\n\nprocessor = Processor()\nprocessor.handler = process_data  # Function is automatically serialized\ndata = processor.serialize()\n```\n\n### 🔒 Strict Mode\n\nEnable strict mode to prevent deserialization of unknown fields:\n\n```python\n# Strict mode raises error for unknown fields\ntry:\n    person.deserialize(data, strict=True)\nexcept ValueError as e:\n    print(f\"Error: {e}\")\n```\n\n### ✅ Validation\n\nValidate that objects can be properly deserialized:\n\n```python\nfrom serilux import validate_serializable_tree\n\n# Validate before serialization\nvalidate_serializable_tree(person)\n```\n\n## 📚 Documentation\n\n**📖 Full documentation available at: [serilux.readthedocs.io](https://serilux.readthedocs.io)**\n\n### Documentation Highlights\n\n- **📘 [User Guide](https://serilux.readthedocs.io/en/latest/user_guide/index.html)**: Comprehensive guide covering all features\n- **🔧 [API Reference](https://serilux.readthedocs.io/en/latest/api_reference/index.html)**: Complete API documentation\n- **💻 [Examples](https://serilux.readthedocs.io/en/latest/examples/index.html)**: Real-world code examples\n\n### Build Documentation Locally\n\n```bash\npip install -e \".[docs]\"\ncd docs \u0026\u0026 make html\n```\n\n## 🎓 Examples\n\nCheck out the `examples/` directory for practical examples:\n\n- **`basic_usage.py`** - Your first serializable class\n- **`advanced_usage.py`** - Nested objects, lists, and dictionaries\n- **`callable_serialization.py`** - Serializing functions, methods, and lambda expressions\n\nRun examples:\n\n```bash\npython examples/basic_usage.py\n```\n\n## 🏗️ Project Structure\n\n```\nserilux/\n├── serilux/              # Main package\n│   ├── __init__.py       # Package initialization\n│   └── serializable.py   # Core serialization classes\n├── tests/                # Comprehensive test suite\n├── examples/             # Usage examples\n└── docs/                 # Sphinx documentation\n```\n\n## 🧪 Testing\n\nSerilux comes with comprehensive tests:\n\n```bash\n# Run all tests\nmake test-all\n\n# Run with coverage\nmake test-cov\n\n# Run specific test suite\npytest tests/\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Star the project** ⭐ - Show your support\n2. **Report bugs** 🐛 - Help us improve\n3. **Suggest features** 💡 - Share your ideas\n4. **Submit PRs** 🔧 - Contribute code\n\n## 🏢 About Agentsmith\n\n**Serilux** is part of the **Agentsmith** open-source ecosystem. Agentsmith is a ToB AI agent and algorithm development platform, currently deployed in multiple highway management companies, securities firms, and regulatory agencies in China. The Agentsmith team is gradually open-sourcing the platform by removing proprietary code and algorithm modules, as well as enterprise-specific customizations, while decoupling the system for modular use by the open-source community.\n\n### 🌟 Agentsmith Open-Source Projects\n\n- **[Varlord](https://github.com/lzjever/varlord)** ⚙️ - Configuration management library with multi-source support\n- **[Routilux](https://github.com/lzjever/routilux)** ⚡ - Event-driven workflow orchestration framework\n- **[Serilux](https://github.com/lzjever/serilux)** 📦 - Flexible serialization framework for Python objects\n- **[Lexilux](https://github.com/lzjever/lexilux)** 🚀 - Unified LLM API client library\n\nThese projects are modular components extracted from the Agentsmith platform, designed to be used independently or together to build powerful applications.\n\n\n## 📄 License\n\nSerilux is licensed under the **Apache License 2.0**. See [LICENSE](LICENSE) for details.\n\n## 🔗 Links\n\n- **📦 PyPI**: [pypi.org/project/serilux](https://pypi.org/project/serilux)\n- **📚 Documentation**: [serilux.readthedocs.io](https://serilux.readthedocs.io)\n- **🐙 GitHub**: [github.com/lzjever/serilux](https://github.com/lzjever/serilux)\n- **📧 Issues**: [github.com/lzjever/serilux/issues](https://github.com/lzjever/serilux/issues)\n\n## ⭐ Show Your Support\n\nIf Serilux helps you build amazing applications, consider giving it a star on GitHub!\n\n---\n\n**Built with ❤️ by the Serilux Team**\n\n*Making object serialization simple, powerful, and fun.*\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzjever%2Fserilux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flzjever%2Fserilux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flzjever%2Fserilux/lists"}