# 🚀 CosmicExcuse
[](https://badge.fury.io/py/cosmicexcuse)
[](https://pypi.org/project/cosmicexcuse/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://pepy.tech/project/cosmicexcuse)
[](https://cosmicexcuse.readthedocs.io/)
> *"It's not a bug, it's a quantum feature!"* 🐛✨
Generate hilarious, technically-sophisticated excuses for when your code doesn't work. Using cutting-edge AI techniques (Markov chains) and quantum computing principles (random.choice()), CosmicExcuse helps you explain any failure with style.
## ✨ Features
- 🌍 **Multi-language Support**: English and Bengali (বাংলা)
- 🎯 **Smart Severity Analysis**: Adapts excuses to error severity
- 🔬 **Quantum-Grade Excuses**: Blame quantum mechanics, cosmic events, or AI sentience
- 📊 **Markov Chain Generation**: Creates believable technical jargon
- 🎋 **Haiku Mode**: Generate poetic excuses
- 🏆 **Excuse Leaderboard**: Track your best excuses
- 📦 **Production Ready**: Type hints, tests, and documentation
- 🚀 **Zero Dependencies**: Pure Python, no external requirements
## 📦 Installation
### Install from PyPI
```bash
pip install cosmicexcuse
```
### Install from Source
```bash
git clone https://github.com/shamspias/cosmicexcuse.git
cd cosmicexcuse
pip install -e .
```
### Install with Extras
```bash
# For development
pip install cosmicexcuse[dev]
# For API server
pip install cosmicexcuse[api]
# For Discord bot
pip install cosmicexcuse[discord]
```
## 🚀 Quick Start
### Basic Usage
```python
from cosmicexcuse import CosmicExcuse
# Initialize the generator
generator = CosmicExcuse()
# Generate an excuse for your error
excuse = generator.generate("FATAL ERROR: Database connection failed!")
print(excuse.text)
# Output: "The error was catastrophically caused by quantum entanglement
# in the CPU cache, resulting in solar flare interference..."
print(excuse.recommendation)
# Output: "Try turning it off and on again, but quantumly"
```
### One-Liner
```python
import cosmicexcuse
print(cosmicexcuse.generate("Segmentation fault"))
```
### Multi-language Support
```python
# Generate excuse in Bengali
generator_bn = CosmicExcuse(language='bn')
excuse = generator_bn.generate("সিস্টেম ক্র্যাশ!")
print(excuse.text)
```
### Command Line Interface
```bash
# Generate a random excuse
cosmicexcuse
# Generate excuse for specific error
cosmicexcuse --error "Failed to compile" --language en
# Generate haiku excuse
cosmicexcuse --haiku
# Generate multiple excuses
cosmicexcuse --count 5 --language bn
```
## 📚 Advanced Usage
### Generate Batch Excuses
```python
from cosmicexcuse import CosmicExcuse
generator = CosmicExcuse()
# Generate multiple excuses
excuses = generator.generate_batch(count=5)
for excuse in excuses:
print(f"Score: {excuse.quality_score}/100")
print(f"Excuse: {excuse.text}\n")
```
### Haiku Mode
```python
# Generate a poetic excuse
haiku = generator.generate_haiku("Memory leak detected")
print(haiku)
# Output:
# Quantum states collapsed
# The servers cry digital tears
# Bits flipped in the void
```
### Category-Specific Excuses
```python
# Generate only quantum-related excuses
excuse = generator.generate(
error_message="Array index out of bounds",
category="quantum"
)
# Generate only AI-related excuses
excuse = generator.generate(
error_message="Model training failed",
category="ai"
)
```
### Track History and Export
```python
generator = CosmicExcuse()
# Generate some excuses
for i in range(10):
generator.generate(f"Error {i}")
# Get the best excuse
best = generator.get_best_excuse()
print(f"Best excuse (score: {best.quality_score}): {best.text}")
# Export history
history_json = generator.export_history(format='json')
history_text = generator.export_history(format='text')
```
### Custom Data Path
```python
from pathlib import Path
from cosmicexcuse import CosmicExcuse
# Use custom excuse data
custom_path = Path("./my_custom_excuses")
generator = CosmicExcuse(data_path=custom_path)
```
## 🏗️ API Server Example
```python
from flask import Flask, jsonify, request
from cosmicexcuse import CosmicExcuse
app = Flask(__name__)
generator = CosmicExcuse()
@app.route('/excuse', methods=['POST'])
def generate_excuse():
data = request.json
error = data.get('error', '')
language = data.get('language', 'en')
generator.language = language
excuse = generator.generate(error)
return jsonify({
'excuse': excuse.text,
'recommendation': excuse.recommendation,
'severity': excuse.severity,
'quality_score': excuse.quality_score
})
if __name__ == '__main__':
app.run(debug=True)
```
## 📊 Excuse Categories
- **Quantum**: Quantum mechanics and physics-based excuses
- **Cosmic**: Space and astronomical phenomena
- **AI**: Machine learning and AI sentience issues
- **Technical**: General technical difficulties
- **Blame**: Blame other developers or systems
- **More categories** in each language!
## 🌍 Supported Languages
- **English (en)**: Full support with extensive excuse database
- **Bengali (bn)**: সম্পূর্ণ বাংলা সমর্থন
- More languages coming soon!
## 🧪 Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=cosmicexcuse
# Run specific test
pytest tests/test_generator.py
```
## 📖 Documentation
Full documentation available at [cosmicexcuse.readthedocs.io](https://cosmicexcuse.readthedocs.io/)
### Building Documentation Locally
```bash
cd docs
make html
open _build/html/index.html
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Adding New Languages
To add a new language:
1. Create a new directory in `cosmicexcuse/data/` with the language code
2. Add JSON files for each excuse category
3. Update `SUPPORTED_LANGUAGES` in `generator.py`
4. Add tests for the new language
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- The cosmic rays that flipped the bits to create this project
- The quantum entanglement that brought you to this README
- The AI that hasn't become sentient yet (we hope)
- All developers who've ever needed a good excuse
## ⚠️ Disclaimer
This tool is for entertainment purposes only. Please do not actually use these excuses in:
- Production incident reports
- Performance reviews
- Client meetings
- Court testimony
- NASA mission control
We are not responsible for any career damage caused by claiming "the blockchain became self-referential" in front of your CTO.
## 🚨 Real Example Outputs
```python
>>> generator.generate("Database connection timeout")
"The error was catastrophically caused by quantum tunneling through the
firewall, thereby triggering the AI achieving consciousness and choosing
violence. Additionally, analysis shows distributed systems consensus
algorithm byzantine fault tolerance instability."
>>> generator.generate("NullPointerException")
"The error was definitely caused by cosmic ray bit flip in critical
memory, which led to microservices forming a union. Additionally,
analysis shows cache miss branch prediction pipeline stall."
>>> generator.generate_haiku()
"Quantum foam bubbles
The data center melts down slow
AI dreams of sheep"
```
## 📈 Project Stats
- 200+ unique quantum excuses
- 150+ cosmic event scenarios
- 100+ AI sentience situations
- 2 supported languages
- ∞ possible combinations
- 0 actual quantum computers harmed
---
**Built with pain and quantum uncertainty**
*Remember: With great code comes great need for excuses.*
⭐ Star us on GitHub if this saved your standup meeting!
Raw data
{
"_id": null,
"home_page": "https://github.com/shamspias/cosmicexcuse",
"name": "cosmicexcuse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "excuse, generator, quantum, ai, humor",
"author": "Shamsuddin Ahmed",
"author_email": "Shamsuddin Ahmed <info@shamspias.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/f7/cc7a9aa7fe87b807c6d8ce8ff010638d134611a93a6c29f260f332dc60c8/cosmicexcuse-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 CosmicExcuse\n\n[](https://badge.fury.io/py/cosmicexcuse)\n[](https://pypi.org/project/cosmicexcuse/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://pepy.tech/project/cosmicexcuse)\n[](https://cosmicexcuse.readthedocs.io/)\n\n> *\"It's not a bug, it's a quantum feature!\"* \ud83d\udc1b\u2728\n\nGenerate hilarious, technically-sophisticated excuses for when your code doesn't work. Using cutting-edge AI techniques (Markov chains) and quantum computing principles (random.choice()), CosmicExcuse helps you explain any failure with style.\n\n## \u2728 Features\n\n- \ud83c\udf0d **Multi-language Support**: English and Bengali (\u09ac\u09be\u0982\u09b2\u09be)\n- \ud83c\udfaf **Smart Severity Analysis**: Adapts excuses to error severity\n- \ud83d\udd2c **Quantum-Grade Excuses**: Blame quantum mechanics, cosmic events, or AI sentience\n- \ud83d\udcca **Markov Chain Generation**: Creates believable technical jargon\n- \ud83c\udf8b **Haiku Mode**: Generate poetic excuses\n- \ud83c\udfc6 **Excuse Leaderboard**: Track your best excuses\n- \ud83d\udce6 **Production Ready**: Type hints, tests, and documentation\n- \ud83d\ude80 **Zero Dependencies**: Pure Python, no external requirements\n\n## \ud83d\udce6 Installation\n\n### Install from PyPI\n\n```bash\npip install cosmicexcuse\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/shamspias/cosmicexcuse.git\ncd cosmicexcuse\npip install -e .\n```\n\n### Install with Extras\n\n```bash\n# For development\npip install cosmicexcuse[dev]\n\n# For API server\npip install cosmicexcuse[api]\n\n# For Discord bot\npip install cosmicexcuse[discord]\n```\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n\n```python\nfrom cosmicexcuse import CosmicExcuse\n\n# Initialize the generator\ngenerator = CosmicExcuse()\n\n# Generate an excuse for your error\nexcuse = generator.generate(\"FATAL ERROR: Database connection failed!\")\n\nprint(excuse.text)\n# Output: \"The error was catastrophically caused by quantum entanglement \n# in the CPU cache, resulting in solar flare interference...\"\n\nprint(excuse.recommendation)\n# Output: \"Try turning it off and on again, but quantumly\"\n```\n\n### One-Liner\n\n```python\nimport cosmicexcuse\nprint(cosmicexcuse.generate(\"Segmentation fault\"))\n```\n\n### Multi-language Support\n\n```python\n# Generate excuse in Bengali\ngenerator_bn = CosmicExcuse(language='bn')\nexcuse = generator_bn.generate(\"\u09b8\u09bf\u09b8\u09cd\u099f\u09c7\u09ae \u0995\u09cd\u09b0\u09cd\u09af\u09be\u09b6!\")\nprint(excuse.text)\n```\n\n### Command Line Interface\n\n```bash\n# Generate a random excuse\ncosmicexcuse\n\n# Generate excuse for specific error\ncosmicexcuse --error \"Failed to compile\" --language en\n\n# Generate haiku excuse\ncosmicexcuse --haiku\n\n# Generate multiple excuses\ncosmicexcuse --count 5 --language bn\n```\n\n## \ud83d\udcda Advanced Usage\n\n### Generate Batch Excuses\n\n```python\nfrom cosmicexcuse import CosmicExcuse\n\ngenerator = CosmicExcuse()\n\n# Generate multiple excuses\nexcuses = generator.generate_batch(count=5)\n\nfor excuse in excuses:\n print(f\"Score: {excuse.quality_score}/100\")\n print(f\"Excuse: {excuse.text}\\n\")\n```\n\n### Haiku Mode\n\n```python\n# Generate a poetic excuse\nhaiku = generator.generate_haiku(\"Memory leak detected\")\nprint(haiku)\n\n# Output:\n# Quantum states collapsed\n# The servers cry digital tears\n# Bits flipped in the void\n```\n\n### Category-Specific Excuses\n\n```python\n# Generate only quantum-related excuses\nexcuse = generator.generate(\n error_message=\"Array index out of bounds\",\n category=\"quantum\"\n)\n\n# Generate only AI-related excuses\nexcuse = generator.generate(\n error_message=\"Model training failed\",\n category=\"ai\"\n)\n```\n\n### Track History and Export\n\n```python\ngenerator = CosmicExcuse()\n\n# Generate some excuses\nfor i in range(10):\n generator.generate(f\"Error {i}\")\n\n# Get the best excuse\nbest = generator.get_best_excuse()\nprint(f\"Best excuse (score: {best.quality_score}): {best.text}\")\n\n# Export history\nhistory_json = generator.export_history(format='json')\nhistory_text = generator.export_history(format='text')\n```\n\n### Custom Data Path\n\n```python\nfrom pathlib import Path\nfrom cosmicexcuse import CosmicExcuse\n\n# Use custom excuse data\ncustom_path = Path(\"./my_custom_excuses\")\ngenerator = CosmicExcuse(data_path=custom_path)\n```\n\n## \ud83c\udfd7\ufe0f API Server Example\n\n```python\nfrom flask import Flask, jsonify, request\nfrom cosmicexcuse import CosmicExcuse\n\napp = Flask(__name__)\ngenerator = CosmicExcuse()\n\n@app.route('/excuse', methods=['POST'])\ndef generate_excuse():\n data = request.json\n error = data.get('error', '')\n language = data.get('language', 'en')\n \n generator.language = language\n excuse = generator.generate(error)\n \n return jsonify({\n 'excuse': excuse.text,\n 'recommendation': excuse.recommendation,\n 'severity': excuse.severity,\n 'quality_score': excuse.quality_score\n })\n\nif __name__ == '__main__':\n app.run(debug=True)\n```\n\n## \ud83d\udcca Excuse Categories\n\n- **Quantum**: Quantum mechanics and physics-based excuses\n- **Cosmic**: Space and astronomical phenomena\n- **AI**: Machine learning and AI sentience issues \n- **Technical**: General technical difficulties\n- **Blame**: Blame other developers or systems\n- **More categories** in each language!\n\n## \ud83c\udf0d Supported Languages\n\n- **English (en)**: Full support with extensive excuse database\n- **Bengali (bn)**: \u09b8\u09ae\u09cd\u09aa\u09c2\u09b0\u09cd\u09a3 \u09ac\u09be\u0982\u09b2\u09be \u09b8\u09ae\u09b0\u09cd\u09a5\u09a8\n- More languages coming soon!\n\n## \ud83e\uddea Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=cosmicexcuse\n\n# Run specific test\npytest tests/test_generator.py\n```\n\n## \ud83d\udcd6 Documentation\n\nFull documentation available at [cosmicexcuse.readthedocs.io](https://cosmicexcuse.readthedocs.io/)\n\n### Building Documentation Locally\n\n```bash\ncd docs\nmake html\nopen _build/html/index.html\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n### Adding New Languages\n\nTo add a new language:\n\n1. Create a new directory in `cosmicexcuse/data/` with the language code\n2. Add JSON files for each excuse category\n3. Update `SUPPORTED_LANGUAGES` in `generator.py`\n4. Add tests for the new language\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- The cosmic rays that flipped the bits to create this project\n- The quantum entanglement that brought you to this README\n- The AI that hasn't become sentient yet (we hope)\n- All developers who've ever needed a good excuse\n\n## \u26a0\ufe0f Disclaimer\n\nThis tool is for entertainment purposes only. Please do not actually use these excuses in:\n- Production incident reports\n- Performance reviews \n- Client meetings\n- Court testimony\n- NASA mission control\n\nWe are not responsible for any career damage caused by claiming \"the blockchain became self-referential\" in front of your CTO.\n\n## \ud83d\udea8 Real Example Outputs\n\n```python\n>>> generator.generate(\"Database connection timeout\")\n\"The error was catastrophically caused by quantum tunneling through the \nfirewall, thereby triggering the AI achieving consciousness and choosing \nviolence. Additionally, analysis shows distributed systems consensus \nalgorithm byzantine fault tolerance instability.\"\n\n>>> generator.generate(\"NullPointerException\")\n\"The error was definitely caused by cosmic ray bit flip in critical \nmemory, which led to microservices forming a union. Additionally, \nanalysis shows cache miss branch prediction pipeline stall.\"\n\n>>> generator.generate_haiku()\n\"Quantum foam bubbles\nThe data center melts down slow \nAI dreams of sheep\"\n```\n\n## \ud83d\udcc8 Project Stats\n\n- 200+ unique quantum excuses\n- 150+ cosmic event scenarios\n- 100+ AI sentience situations\n- 2 supported languages\n- \u221e possible combinations\n- 0 actual quantum computers harmed\n\n---\n\n**Built with pain and quantum uncertainty**\n\n*Remember: With great code comes great need for excuses.*\n\n\u2b50 Star us on GitHub if this saved your standup meeting!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate quantum-grade excuses for your code failures using fake AI",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/shamspias/cosmicexcuse/issues",
"Documentation": "https://cosmicexcuse.readthedocs.io/",
"Homepage": "https://github.com/shamspias/cosmicexcuse"
},
"split_keywords": [
"excuse",
" generator",
" quantum",
" ai",
" humor"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5d9d7b610a1955f74b0e3b7b7926482231accb0d5906a7ebfd9f147a22e8d27b",
"md5": "fb8ab94beacd3d5357905fdc358a062d",
"sha256": "40e6ffc5113ec5d4838da153b13553d25ffe45cfe6cc3440a52112231a0f571b"
},
"downloads": -1,
"filename": "cosmicexcuse-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb8ab94beacd3d5357905fdc358a062d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 48043,
"upload_time": "2025-08-26T10:37:32",
"upload_time_iso_8601": "2025-08-26T10:37:32.326720Z",
"url": "https://files.pythonhosted.org/packages/5d/9d/7b610a1955f74b0e3b7b7926482231accb0d5906a7ebfd9f147a22e8d27b/cosmicexcuse-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e4f7cc7a9aa7fe87b807c6d8ce8ff010638d134611a93a6c29f260f332dc60c8",
"md5": "22e2a8b7521e662c3c8c1a9119eedda2",
"sha256": "a92132dd0b015f38370787db703442dd3044de452ea379af913ff174b7d2a8a7"
},
"downloads": -1,
"filename": "cosmicexcuse-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "22e2a8b7521e662c3c8c1a9119eedda2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 52569,
"upload_time": "2025-08-26T10:37:33",
"upload_time_iso_8601": "2025-08-26T10:37:33.962089Z",
"url": "https://files.pythonhosted.org/packages/e4/f7/cc7a9aa7fe87b807c6d8ce8ff010638d134611a93a6c29f260f332dc60c8/cosmicexcuse-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 10:37:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shamspias",
"github_project": "cosmicexcuse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cosmicexcuse"
}
JSON
