# 🚀 eXonware Python Library Template
**Company:** eXonware.com
**Author:** Eng. Muhammad AlShehri
**Email:** connect@exonware.com
**Version:** 0.0.1
**Template Version:** 1.0.0
## 🎯 **What This Template Is**
This is a production-ready Python library template based on the successful xSystem architecture. It provides a complete, standardized foundation for creating new Python libraries in the eXonware ecosystem with all the necessary files, structure, and configurations pre-configured.
## 🤖 **AI Usage Instructions - READ THIS FIRST**
### **For AI Assistants Using This Template**
When a user asks you to create a new Python library using this template, follow these steps:
#### **Step 1: Copy the Template**
1. Copy the entire `templates/python-lib/` directory to the new library location
2. Rename the directory to the new library name (e.g., `xdata`, `xnode`, `xaction`)
#### **Step 2: Replace All Placeholders**
Search and replace ALL occurrences of these placeholders throughout ALL files:
| Placeholder | Replace With | Example |
|-------------|-------------|---------|
| `xaction` | The actual library name | `xdata` |
| `Action-based workflow and automation library` | Brief description | `Advanced data manipulation library` |
| `"action", "workflow", "automation", "execution", "tasks"` | Comma-separated keywords | `"data", "manipulation", "processing"` |
| `February 2, 2025` | Current date | `January 31, 2025` |
| `xaction` | The actual library name | `xdata` |
#### **Step 3: File and Directory Renaming**
1. Rename `src/exonware/xaction/` to `src/exonware/xaction/`
2. Rename `src/xaction.py` to the actual library name
3. Update all import paths in test files
#### **Step 4: Update Package Configuration**
1. Update `pyproject.toml` with specific dependencies for the new library
2. Update `requirements.txt` with library-specific dependencies
3. Verify all placeholder replacements are complete
#### **Step 5: Verify Structure**
Ensure the final structure matches this pattern:
```
new-library/
├── .github/workflows/publish.yml
├── .gitignore
├── README.md
├── requirements.txt
├── pyproject.toml
├── src/
│ ├── exonware/
│ │ └── xaction/
│ │ └── __init__.py
│ └── xaction.py
├── tests/
│ ├── __init__.py
│ ├── runner.py
│ ├── core/
│ │ ├── __init__.py
│ │ ├── conftest.py
│ │ ├── runner.py
│ │ ├── test_core.py
│ │ └── data/
│ │ ├── expected/
│ │ ├── fixtures/
│ │ └── inputs/
│ ├── unit/
│ │ ├── __init__.py
│ │ └── runner.py
│ └── integration/
│ ├── __init__.py
│ └── runner.py
├── docs/
│ └── README.md
└── examples/
└── basic_example.py
```
### **Critical AI Instructions**
1. **NEVER skip placeholder replacement** - Every `{PLACEHOLDER}` must be replaced
2. **ALWAYS rename directories** - Don't leave `xaction` in the structure
3. **ALWAYS update imports** - Test files must import the correct library name
4. **ALWAYS verify** - Check that the library can be imported after setup
5. **Follow eXonware standards** - Use the established naming conventions and structure
## 📋 **Template Contents**
### **🗂️ Project Structure**
- **Complete directory structure** matching xSystem architecture
- **Empty source directories** ready for implementation
- **Test framework** with core/unit/integration separation
- **Documentation structure** with docs/ folder
- **Examples directory** for usage demonstrations
### **⚙️ Configuration Files**
- **`pyproject.toml`** - Modern Python packaging with Hatch build system
- **`requirements.txt`** - Comprehensive dependency management
- **`.gitignore`** - Production-ready Git ignore rules
- **`.github/workflows/publish.yml`** - Automated PyPI publishing
### **🧪 Testing Infrastructure**
- **pytest configuration** with proper markers and test discovery
- **Three-tier test structure**: core, unit, integration
- **Test runners** for each test category
- **Sample test files** with proper imports and fixtures
### **📚 Documentation Framework**
- **Main README.md** with template structure
- **docs/README.md** for detailed documentation
- **Examples directory** with basic usage examples
## 🛠️ **Manual Usage (For Developers)**
If you're manually using this template (not via AI):
### **Step 1: Copy Template**
```bash
cp -r templates/python-lib/ ../your-new-library/
cd ../your-new-library/
```
### **Step 2: Find and Replace**
Use your editor's find-and-replace across all files:
- `xaction` → your library name
- `Action-based workflow and automation library` → your library description
- `"action", "workflow", "automation", "execution", "tasks"` → your keywords
- `February 2, 2025` → current date
- `xaction` → your library name
### **Step 3: Rename Directories**
```bash
mv src/exonware/xaction src/exonware/your-library-name
```
### **Step 4: Test the Setup**
```bash
python -m pytest tests/ -v
python examples/basic_example.py
```
## 🎯 **Template Features**
### **✅ Production-Ready Configuration**
- Modern `pyproject.toml` with Hatch build system
- Comprehensive `requirements.txt` with version constraints
- Professional `.gitignore` covering all common patterns
- GitHub Actions for automated PyPI publishing
### **✅ eXonware Standards Compliance**
- Follows established naming conventions (`exonware-{library}`)
- Dual import support (`exonware.library` and `library`)
- Consistent file headers with company information
- Standard test structure (core/unit/integration)
### **✅ Developer Experience**
- Multiple test runners for different test types
- Example files for quick start
- Documentation templates
- Proper Python path handling in tests
### **✅ CI/CD Ready**
- GitHub Actions workflow for PyPI publishing
- Pytest configuration with coverage
- Code quality tools (black, isort, mypy) configured
- Version management through tags
## 🔧 **Customization Points**
When creating a new library, customize these areas:
1. **Dependencies** - Add specific requirements in `pyproject.toml` and `requirements.txt`
2. **Keywords** - Update package keywords for PyPI discoverability
3. **Classifiers** - Add specific PyPI classifiers for your library type
4. **Test markers** - Add library-specific pytest markers
5. **Examples** - Create meaningful examples for your library's use cases
## 📝 **Best Practices**
### **For AI Implementation**
- Always verify placeholder replacement is complete
- Test imports after setup to ensure everything works
- Follow the three-tier test structure (core/unit/integration)
- Use meaningful commit messages when creating the new library
### **For Manual Implementation**
- Start with the basic template and gradually add features
- Write tests as you implement functionality
- Keep documentation updated with API changes
- Use semantic versioning for releases
## 🚀 **Getting Started After Template Setup**
1. **Implement your core functionality** in `src/exonware/xaction/`
2. **Add your dependencies** to `pyproject.toml` and `requirements.txt`
3. **Write tests** in the appropriate test directories
4. **Update documentation** with your API and examples
5. **Create meaningful examples** showing library usage
6. **Set up PyPI publishing** by adding `PYPI_API_TOKEN` to GitHub secrets
## 📚 **Related Documentation**
- **[eXonware Development Standards](../docs/)** - Company-wide development guidelines
- **[xSystem Architecture](../xsystem/)** - Reference implementation this template is based on
- **[Testing Guidelines](../docs/TESTING.md)** - How to write effective tests
- **[Publishing Guide](../tools/ci/)** - How to publish to PyPI
## 🤝 **Contributing to This Template**
If you need to improve this template:
1. Make changes to files in `templates/python-lib/`
2. Update this README with any new features or changes
3. Test the template by creating a sample library
4. Ensure all placeholders work correctly
5. Update the AI instructions if the process changes
## 🔍 **Template Validation Checklist**
Before using this template, verify:
- [ ] All placeholder patterns are consistent
- [ ] Directory structure matches eXonware standards
- [ ] Test framework is properly configured
- [ ] GitHub Actions workflow is valid
- [ ] Documentation templates are complete
- [ ] Example files demonstrate proper usage
- [ ] Import paths are correct in all files
---
## 🏆 **This Template Provides**
✅ **Complete project structure** based on proven xSystem architecture
✅ **Production-ready configuration** with modern Python tooling
✅ **Comprehensive testing framework** with three-tier organization
✅ **Automated CI/CD** with GitHub Actions and PyPI publishing
✅ **eXonware standards compliance** for consistency across libraries
✅ **AI-friendly design** with clear placeholder patterns
✅ **Developer experience** optimized for rapid library development
✅ **Documentation framework** for professional library documentation
*Built with ❤️ by eXonware.com - Making Python library development effortless*
Raw data
{
"_id": null,
"home_page": null,
"name": "exonware-xaction",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "action, automation, execution, exonware, tasks, workflow",
"author": null,
"author_email": "\"Eng. Muhammad AlShehri\" <connect@exonware.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/c4/3745697f1e72c9582ae859cab7703e17e006bb87c4cf5ad153293185318f/exonware_xaction-0.0.1.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 eXonware Python Library Template\n\n**Company:** eXonware.com \n**Author:** Eng. Muhammad AlShehri \n**Email:** connect@exonware.com \n**Version:** 0.0.1 \n**Template Version:** 1.0.0 \n\n## \ud83c\udfaf **What This Template Is**\n\nThis is a production-ready Python library template based on the successful xSystem architecture. It provides a complete, standardized foundation for creating new Python libraries in the eXonware ecosystem with all the necessary files, structure, and configurations pre-configured.\n\n## \ud83e\udd16 **AI Usage Instructions - READ THIS FIRST**\n\n### **For AI Assistants Using This Template**\n\nWhen a user asks you to create a new Python library using this template, follow these steps:\n\n#### **Step 1: Copy the Template**\n1. Copy the entire `templates/python-lib/` directory to the new library location\n2. Rename the directory to the new library name (e.g., `xdata`, `xnode`, `xaction`)\n\n#### **Step 2: Replace All Placeholders**\nSearch and replace ALL occurrences of these placeholders throughout ALL files:\n\n| Placeholder | Replace With | Example |\n|-------------|-------------|---------|\n| `xaction` | The actual library name | `xdata` |\n| `Action-based workflow and automation library` | Brief description | `Advanced data manipulation library` |\n| `\"action\", \"workflow\", \"automation\", \"execution\", \"tasks\"` | Comma-separated keywords | `\"data\", \"manipulation\", \"processing\"` |\n| `February 2, 2025` | Current date | `January 31, 2025` |\n| `xaction` | The actual library name | `xdata` |\n\n#### **Step 3: File and Directory Renaming**\n1. Rename `src/exonware/xaction/` to `src/exonware/xaction/`\n2. Rename `src/xaction.py` to the actual library name\n3. Update all import paths in test files\n\n#### **Step 4: Update Package Configuration**\n1. Update `pyproject.toml` with specific dependencies for the new library\n2. Update `requirements.txt` with library-specific dependencies\n3. Verify all placeholder replacements are complete\n\n#### **Step 5: Verify Structure**\nEnsure the final structure matches this pattern:\n```\nnew-library/\n\u251c\u2500\u2500 .github/workflows/publish.yml\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 exonware/\n\u2502 \u2502 \u2514\u2500\u2500 xaction/\n\u2502 \u2502 \u2514\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 xaction.py\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 runner.py\n\u2502 \u251c\u2500\u2500 core/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 conftest.py\n\u2502 \u2502 \u251c\u2500\u2500 runner.py\n\u2502 \u2502 \u251c\u2500\u2500 test_core.py\n\u2502 \u2502 \u2514\u2500\u2500 data/\n\u2502 \u2502 \u251c\u2500\u2500 expected/\n\u2502 \u2502 \u251c\u2500\u2500 fixtures/\n\u2502 \u2502 \u2514\u2500\u2500 inputs/\n\u2502 \u251c\u2500\u2500 unit/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 runner.py\n\u2502 \u2514\u2500\u2500 integration/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 runner.py\n\u251c\u2500\u2500 docs/\n\u2502 \u2514\u2500\u2500 README.md\n\u2514\u2500\u2500 examples/\n \u2514\u2500\u2500 basic_example.py\n```\n\n### **Critical AI Instructions**\n\n1. **NEVER skip placeholder replacement** - Every `{PLACEHOLDER}` must be replaced\n2. **ALWAYS rename directories** - Don't leave `xaction` in the structure\n3. **ALWAYS update imports** - Test files must import the correct library name\n4. **ALWAYS verify** - Check that the library can be imported after setup\n5. **Follow eXonware standards** - Use the established naming conventions and structure\n\n## \ud83d\udccb **Template Contents**\n\n### **\ud83d\uddc2\ufe0f Project Structure**\n- **Complete directory structure** matching xSystem architecture\n- **Empty source directories** ready for implementation\n- **Test framework** with core/unit/integration separation\n- **Documentation structure** with docs/ folder\n- **Examples directory** for usage demonstrations\n\n### **\u2699\ufe0f Configuration Files**\n- **`pyproject.toml`** - Modern Python packaging with Hatch build system\n- **`requirements.txt`** - Comprehensive dependency management\n- **`.gitignore`** - Production-ready Git ignore rules\n- **`.github/workflows/publish.yml`** - Automated PyPI publishing\n\n### **\ud83e\uddea Testing Infrastructure**\n- **pytest configuration** with proper markers and test discovery\n- **Three-tier test structure**: core, unit, integration\n- **Test runners** for each test category\n- **Sample test files** with proper imports and fixtures\n\n### **\ud83d\udcda Documentation Framework**\n- **Main README.md** with template structure\n- **docs/README.md** for detailed documentation\n- **Examples directory** with basic usage examples\n\n## \ud83d\udee0\ufe0f **Manual Usage (For Developers)**\n\nIf you're manually using this template (not via AI):\n\n### **Step 1: Copy Template**\n```bash\ncp -r templates/python-lib/ ../your-new-library/\ncd ../your-new-library/\n```\n\n### **Step 2: Find and Replace**\nUse your editor's find-and-replace across all files:\n- `xaction` \u2192 your library name\n- `Action-based workflow and automation library` \u2192 your library description \n- `\"action\", \"workflow\", \"automation\", \"execution\", \"tasks\"` \u2192 your keywords\n- `February 2, 2025` \u2192 current date\n- `xaction` \u2192 your library name\n\n### **Step 3: Rename Directories**\n```bash\nmv src/exonware/xaction src/exonware/your-library-name\n```\n\n### **Step 4: Test the Setup**\n```bash\npython -m pytest tests/ -v\npython examples/basic_example.py\n```\n\n## \ud83c\udfaf **Template Features**\n\n### **\u2705 Production-Ready Configuration**\n- Modern `pyproject.toml` with Hatch build system\n- Comprehensive `requirements.txt` with version constraints\n- Professional `.gitignore` covering all common patterns\n- GitHub Actions for automated PyPI publishing\n\n### **\u2705 eXonware Standards Compliance**\n- Follows established naming conventions (`exonware-{library}`)\n- Dual import support (`exonware.library` and `library`)\n- Consistent file headers with company information\n- Standard test structure (core/unit/integration)\n\n### **\u2705 Developer Experience**\n- Multiple test runners for different test types\n- Example files for quick start\n- Documentation templates\n- Proper Python path handling in tests\n\n### **\u2705 CI/CD Ready**\n- GitHub Actions workflow for PyPI publishing\n- Pytest configuration with coverage\n- Code quality tools (black, isort, mypy) configured\n- Version management through tags\n\n## \ud83d\udd27 **Customization Points**\n\nWhen creating a new library, customize these areas:\n\n1. **Dependencies** - Add specific requirements in `pyproject.toml` and `requirements.txt`\n2. **Keywords** - Update package keywords for PyPI discoverability \n3. **Classifiers** - Add specific PyPI classifiers for your library type\n4. **Test markers** - Add library-specific pytest markers\n5. **Examples** - Create meaningful examples for your library's use cases\n\n## \ud83d\udcdd **Best Practices**\n\n### **For AI Implementation**\n- Always verify placeholder replacement is complete\n- Test imports after setup to ensure everything works\n- Follow the three-tier test structure (core/unit/integration)\n- Use meaningful commit messages when creating the new library\n\n### **For Manual Implementation** \n- Start with the basic template and gradually add features\n- Write tests as you implement functionality\n- Keep documentation updated with API changes\n- Use semantic versioning for releases\n\n## \ud83d\ude80 **Getting Started After Template Setup**\n\n1. **Implement your core functionality** in `src/exonware/xaction/`\n2. **Add your dependencies** to `pyproject.toml` and `requirements.txt`\n3. **Write tests** in the appropriate test directories\n4. **Update documentation** with your API and examples\n5. **Create meaningful examples** showing library usage\n6. **Set up PyPI publishing** by adding `PYPI_API_TOKEN` to GitHub secrets\n\n## \ud83d\udcda **Related Documentation**\n\n- **[eXonware Development Standards](../docs/)** - Company-wide development guidelines\n- **[xSystem Architecture](../xsystem/)** - Reference implementation this template is based on\n- **[Testing Guidelines](../docs/TESTING.md)** - How to write effective tests\n- **[Publishing Guide](../tools/ci/)** - How to publish to PyPI\n\n## \ud83e\udd1d **Contributing to This Template**\n\nIf you need to improve this template:\n\n1. Make changes to files in `templates/python-lib/`\n2. Update this README with any new features or changes\n3. Test the template by creating a sample library\n4. Ensure all placeholders work correctly\n5. Update the AI instructions if the process changes\n\n## \ud83d\udd0d **Template Validation Checklist**\n\nBefore using this template, verify:\n\n- [ ] All placeholder patterns are consistent\n- [ ] Directory structure matches eXonware standards \n- [ ] Test framework is properly configured\n- [ ] GitHub Actions workflow is valid\n- [ ] Documentation templates are complete\n- [ ] Example files demonstrate proper usage\n- [ ] Import paths are correct in all files\n\n---\n\n## \ud83c\udfc6 **This Template Provides**\n\n\u2705 **Complete project structure** based on proven xSystem architecture \n\u2705 **Production-ready configuration** with modern Python tooling \n\u2705 **Comprehensive testing framework** with three-tier organization \n\u2705 **Automated CI/CD** with GitHub Actions and PyPI publishing \n\u2705 **eXonware standards compliance** for consistency across libraries \n\u2705 **AI-friendly design** with clear placeholder patterns \n\u2705 **Developer experience** optimized for rapid library development \n\u2705 **Documentation framework** for professional library documentation \n\n*Built with \u2764\ufe0f by eXonware.com - Making Python library development effortless*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Action-based workflow and automation library",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://github.com/exonware/xaction#readme",
"Homepage": "https://exonware.com",
"Repository": "https://github.com/exonware/xaction"
},
"split_keywords": [
"action",
" automation",
" execution",
" exonware",
" tasks",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "91c48f9685be4df6cb47269da495272f24b0558bcb6e1d3dc96d8cf44431b10d",
"md5": "be37f6cd275be9531dfaed4fa8f186ac",
"sha256": "33bdb39b9831a839f59488dd25469b24ee91a9a5ca9dbcd5de70658eb3d3d943"
},
"downloads": -1,
"filename": "exonware_xaction-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be37f6cd275be9531dfaed4fa8f186ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6004,
"upload_time": "2025-09-02T22:49:13",
"upload_time_iso_8601": "2025-09-02T22:49:13.098828Z",
"url": "https://files.pythonhosted.org/packages/91/c4/8f9685be4df6cb47269da495272f24b0558bcb6e1d3dc96d8cf44431b10d/exonware_xaction-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1c43745697f1e72c9582ae859cab7703e17e006bb87c4cf5ad153293185318f",
"md5": "518f1b6eff93d9b3e108bc93e277caa3",
"sha256": "a835c2e13b26f3fe6eed2669cf620e3744fb6fbf002ef5f8faa23d6ac97bcfac"
},
"downloads": -1,
"filename": "exonware_xaction-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "518f1b6eff93d9b3e108bc93e277caa3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9926,
"upload_time": "2025-09-02T22:49:14",
"upload_time_iso_8601": "2025-09-02T22:49:14.410298Z",
"url": "https://files.pythonhosted.org/packages/b1/c4/3745697f1e72c9582ae859cab7703e17e006bb87c4cf5ad153293185318f/exonware_xaction-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 22:49:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exonware",
"github_project": "xaction#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.20.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"22.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
">=",
"5.10.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"0.950"
]
]
}
],
"lcname": "exonware-xaction"
}
JSON
