| Name | captain-arro JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Animated SVG arrow generators for web interfaces |
| upload_time | 2025-08-02 09:45:51 |
| maintainer | Helge Esch |
| docs_url | None |
| author | Helge Esch |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 helgeesch
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
svg
animation
arrows
graphics
web
ui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Captain Arro ⬅⛵️➡
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**Captain Arro** is a Python library for generating animated SVG arrows for web interfaces. Create beautiful, customizable arrow animations with just a few lines of code.
Yes, this package is totally vibe coded. It's useful anyhow!
## Features
- 🎯 **Four arrow types**: Moving flow, spotlight flow, bouncing spread, and spotlight spread
- 🎨 **Fully customizable**: Colors, sizes, speeds, directions, and animations
- 🔧 **Type-safe**: Full TypeScript-style type hints for better development experience
- 📦 **Zero dependencies**: Pure Python implementation
- 🌐 **Web-ready**: Generates clean SVG code for direct HTML embedding
## Installation
```bash
pip install captain-arro
```
## Quick Start
```python
from captain_arro import MovingFlowArrowGenerator
# Create a simple right-pointing arrow
generator = MovingFlowArrowGenerator()
svg_content = generator.generate_svg()
# Save to file
generator.save_to_file("my_arrow.svg")
```
## Arrow Types
### 1. Moving Flow Arrows
Arrows that move continuously in one direction with a flowing animation.
```python
from captain_arro import MovingFlowArrowGenerator
# Blue arrows moving right
generator = MovingFlowArrowGenerator(
direction="right",
stroke_width=8,
color="#3b82f6",
num_arrows=6,
width=150,
height=100,
speed_in_px_per_second=25,
animation="ease-in-out"
)
```
### 2. Spotlight Flow Arrows
Arrows with a moving spotlight effect that highlights different parts.
```python
from captain_arro import SpotlightFlowArrowGenerator
# Purple spotlight effect
generator = SpotlightFlowArrowGenerator(
direction="right",
color="#8b5cf6",
num_arrows=3,
width=180,
height=120,
speed_in_px_per_second=40.0,
spotlight_size=0.3,
dim_opacity=0.5
)
```
### 3. Bouncing Spread Arrows
Arrows that spread outward from center with a bouncing animation.
```python
from captain_arro import BouncingSpreadArrowGenerator
# Teal arrows spreading horizontally
generator = BouncingSpreadArrowGenerator(
direction="horizontal",
color="#14b8a6",
num_arrows=4,
width=250,
height=100,
speed_in_px_per_second=15.0,
animation="ease-in-out",
center_gap_ratio=0.3,
stroke_width=10
)
```
### 4. Spotlight Spread Arrows
Spread arrows with spotlight effects radiating from center.
```python
from captain_arro import SpotlightSpreadArrowGenerator
# Indigo spotlight spreading horizontally
generator = SpotlightSpreadArrowGenerator(
direction="horizontal",
color="#6366f1",
stroke_width=12,
num_arrows=8,
width=300,
height=100,
speed_in_px_per_second=100.0,
spotlight_size=0.25,
dim_opacity=0.5,
center_gap_ratio=0.3,
)
```
## Configuration Options
### Common Parameters
All generators support these base parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `color` | `str` | `"#2563eb"` | Arrow color (hex, rgb, named colors) |
| `stroke_width` | `int` | `10` | Line thickness (min: 2) |
| `width` | `int` | `100` | SVG width in pixels |
| `height` | `int` | `100` | SVG height in pixels |
| `speed` | `float` | `20.0` | Animation speed (pixels per second) |
| `num_arrows` | `int` | `4` | Number of arrows to display |
### Flow Arrow Parameters
| Parameter | Type | Options | Description |
|-----------|------|---------|-------------|
| `direction` | `FLOW_DIRECTIONS` | `"right"`, `"left"`, `"up"`, `"down"` | Arrow movement direction |
| `animation` | `ANIMATION_TYPES` | `"ease-in-out"`, `"linear"`, `"ease"`, etc. | Animation timing function |
### Spotlight Parameters
| Parameter | Type | Default | Description |
|-----------------------------------|------|---------|-------------------------------------------------------|
| `spotlight_size` | `float` | `0.3` | Size of spotlight effect (0.1-1.0) |
| `spotlight_path_extension_factor` | `float` | `1.0` | Factor by which the path of the spotlight is extended |
| `dim_opacity` | `float` | `0.2` | Opacity of dimmed areas (0.0-1.0) |
### Spread Arrow Parameters
| Parameter | Type | Options | Description |
|-----------|------|---------|-------------|
| `direction` | `SPREAD_DIRECTIONS` | `"horizontal"`, `"vertical"` | Spread orientation |
| `center_gap_ratio` | `float` | `0.2` | Gap size in center (0.1-0.4) |
## Advanced Usage
### Custom Animations
```python
from captain_arro import MovingFlowArrowGenerator
# Fast linear animation upward
generator = MovingFlowArrowGenerator(
direction="up",
speed_in_px_per_second=50.0,
animation="linear",
num_arrows=6
)
```
### Responsive Sizing
```python
# Large arrow for desktop
desktop_arrow = MovingFlowArrowGenerator(width=300, height=120)
# Small arrow for mobile
mobile_arrow = MovingFlowArrowGenerator(width=150, height=60)
```
### Color Theming
```python
# Dark theme
dark_arrow = SpotlightFlowArrowGenerator(
color="#ffffff",
dim_opacity=0.1
)
# Brand colors
brand_arrow = BouncingSpreadArrowGenerator(
color="#your-brand-color"
)
```
## HTML Integration
Embed generated SVGs directly in your HTML:
```html
<!-- Option 1: Inline SVG -->
<div class="arrow-container">
<!-- Paste SVG content here -->
</div>
<!-- Option 2: External file -->
<img src="path/to/arrow.svg" alt="Animated arrow" />
<!-- Option 3: CSS background -->
<div style="background-image: url('path/to/arrow.svg')"></div>
```
## Type Safety
Captain Arro includes full type annotations for excellent IDE support:
```python
from captain_arro import FLOW_DIRECTIONS, ANIMATION_TYPES
# TypeScript-style literal types
direction: FLOW_DIRECTIONS = "right" # ✅ Valid
direction: FLOW_DIRECTIONS = "invalid" # ❌ Type error
animation: ANIMATION_TYPES = "ease-in-out" # ✅ Valid
animation: ANIMATION_TYPES = "bounce" # ❌ Type error
```
## Examples
The `examples/` directory contains comprehensive usage examples:
```bash
# Generate all example SVGs
python examples/basic_usage.py
# View examples
ls examples/output/
```
See [`examples/README.md`](examples/README.md) for detailed descriptions of each example.
## Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=captain_arro
```
### Code Quality
```bash
# Format code
black captain_arro tests examples
# Sort imports
isort captain_arro tests examples
# Type checking
mypy captain_arro
# Linting
flake8 captain_arro tests examples
```
## API Reference
### Base Classes
- `AnimatedArrowGeneratorBase` - Abstract base class for all generators
### Generator Classes
- `MovingFlowArrowGenerator` - Moving flow arrows
- `SpotlightFlowArrowGenerator` - Spotlight flow arrows
- `BouncingSpreadArrowGenerator` - Bouncing spread arrows
- `SpotlightSpreadArrowGenerator` - Spotlight spread arrows
### Type Definitions
- `ANIMATION_TYPES` - Valid animation timing functions
- `FLOW_DIRECTIONS` - Valid flow directions
- `SPREAD_DIRECTIONS` - Valid spread directions
## Browser Compatibility
Generated SVGs work in all modern browsers that support:
- SVG animations (`animateTransform`)
- CSS animations (`@keyframes`)
- Linear gradients
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
### v0.1.0
- Initial release
- Four arrow generator types
- Full type safety
- Comprehensive test suite
- Documentation and examples
---
Made with ❤️ and good vibes
Raw data
{
"_id": null,
"home_page": null,
"name": "captain-arro",
"maintainer": "Helge Esch",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "svg, animation, arrows, graphics, web, ui",
"author": "Helge Esch",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0c/cd/b55ccca1fac768170ec0fb7f503e863967375abbfd9db731e314f7fa0233/captain_arro-0.1.0.tar.gz",
"platform": null,
"description": "# Captain Arro \u2b05\u26f5\ufe0f\u27a1\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n**Captain Arro** is a Python library for generating animated SVG arrows for web interfaces. Create beautiful, customizable arrow animations with just a few lines of code.\n\nYes, this package is totally vibe coded. It's useful anyhow!\n\n## Features\n\n- \ud83c\udfaf **Four arrow types**: Moving flow, spotlight flow, bouncing spread, and spotlight spread\n- \ud83c\udfa8 **Fully customizable**: Colors, sizes, speeds, directions, and animations\n- \ud83d\udd27 **Type-safe**: Full TypeScript-style type hints for better development experience\n- \ud83d\udce6 **Zero dependencies**: Pure Python implementation\n- \ud83c\udf10 **Web-ready**: Generates clean SVG code for direct HTML embedding\n\n## Installation\n\n```bash\npip install captain-arro\n```\n\n## Quick Start\n\n```python\nfrom captain_arro import MovingFlowArrowGenerator\n\n# Create a simple right-pointing arrow\ngenerator = MovingFlowArrowGenerator()\nsvg_content = generator.generate_svg()\n\n# Save to file\ngenerator.save_to_file(\"my_arrow.svg\")\n```\n\n## Arrow Types\n\n### 1. Moving Flow Arrows\n\nArrows that move continuously in one direction with a flowing animation.\n\n```python\nfrom captain_arro import MovingFlowArrowGenerator\n\n# Blue arrows moving right\ngenerator = MovingFlowArrowGenerator(\n direction=\"right\",\n stroke_width=8,\n color=\"#3b82f6\", \n num_arrows=6,\n width=150,\n height=100,\n speed_in_px_per_second=25,\n animation=\"ease-in-out\"\n)\n```\n\n\n\n### 2. Spotlight Flow Arrows \n\nArrows with a moving spotlight effect that highlights different parts.\n\n```python\nfrom captain_arro import SpotlightFlowArrowGenerator\n\n# Purple spotlight effect\ngenerator = SpotlightFlowArrowGenerator(\n direction=\"right\",\n color=\"#8b5cf6\",\n num_arrows=3,\n width=180,\n height=120,\n speed_in_px_per_second=40.0,\n spotlight_size=0.3,\n dim_opacity=0.5\n)\n```\n\n\n\n### 3. Bouncing Spread Arrows\n\nArrows that spread outward from center with a bouncing animation.\n\n```python\nfrom captain_arro import BouncingSpreadArrowGenerator\n\n# Teal arrows spreading horizontally \ngenerator = BouncingSpreadArrowGenerator(\n direction=\"horizontal\",\n color=\"#14b8a6\",\n num_arrows=4,\n width=250,\n height=100,\n speed_in_px_per_second=15.0,\n animation=\"ease-in-out\",\n center_gap_ratio=0.3,\n stroke_width=10\n)\n```\n\n\n\n### 4. Spotlight Spread Arrows\n\nSpread arrows with spotlight effects radiating from center.\n\n```python\nfrom captain_arro import SpotlightSpreadArrowGenerator\n\n# Indigo spotlight spreading horizontally\ngenerator = SpotlightSpreadArrowGenerator(\n direction=\"horizontal\",\n color=\"#6366f1\",\n stroke_width=12,\n num_arrows=8,\n width=300,\n height=100,\n speed_in_px_per_second=100.0,\n spotlight_size=0.25,\n dim_opacity=0.5,\n center_gap_ratio=0.3,\n)\n```\n\n\n\n## Configuration Options\n\n### Common Parameters\n\nAll generators support these base parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `color` | `str` | `\"#2563eb\"` | Arrow color (hex, rgb, named colors) |\n| `stroke_width` | `int` | `10` | Line thickness (min: 2) |\n| `width` | `int` | `100` | SVG width in pixels |\n| `height` | `int` | `100` | SVG height in pixels |\n| `speed` | `float` | `20.0` | Animation speed (pixels per second) |\n| `num_arrows` | `int` | `4` | Number of arrows to display |\n\n### Flow Arrow Parameters\n\n| Parameter | Type | Options | Description |\n|-----------|------|---------|-------------|\n| `direction` | `FLOW_DIRECTIONS` | `\"right\"`, `\"left\"`, `\"up\"`, `\"down\"` | Arrow movement direction |\n| `animation` | `ANIMATION_TYPES` | `\"ease-in-out\"`, `\"linear\"`, `\"ease\"`, etc. | Animation timing function |\n\n### Spotlight Parameters\n\n| Parameter | Type | Default | Description |\n|-----------------------------------|------|---------|-------------------------------------------------------|\n| `spotlight_size` | `float` | `0.3` | Size of spotlight effect (0.1-1.0) |\n| `spotlight_path_extension_factor` | `float` | `1.0` | Factor by which the path of the spotlight is extended |\n| `dim_opacity` | `float` | `0.2` | Opacity of dimmed areas (0.0-1.0) |\n\n### Spread Arrow Parameters \n\n| Parameter | Type | Options | Description |\n|-----------|------|---------|-------------|\n| `direction` | `SPREAD_DIRECTIONS` | `\"horizontal\"`, `\"vertical\"` | Spread orientation |\n| `center_gap_ratio` | `float` | `0.2` | Gap size in center (0.1-0.4) |\n\n## Advanced Usage\n\n### Custom Animations\n\n```python\nfrom captain_arro import MovingFlowArrowGenerator\n\n# Fast linear animation upward\ngenerator = MovingFlowArrowGenerator(\n direction=\"up\",\n speed_in_px_per_second=50.0,\n animation=\"linear\",\n num_arrows=6\n)\n```\n\n### Responsive Sizing\n\n```python\n# Large arrow for desktop\ndesktop_arrow = MovingFlowArrowGenerator(width=300, height=120)\n\n# Small arrow for mobile \nmobile_arrow = MovingFlowArrowGenerator(width=150, height=60)\n```\n\n### Color Theming\n\n```python\n# Dark theme\ndark_arrow = SpotlightFlowArrowGenerator(\n color=\"#ffffff\",\n dim_opacity=0.1\n)\n\n# Brand colors\nbrand_arrow = BouncingSpreadArrowGenerator(\n color=\"#your-brand-color\"\n)\n```\n\n## HTML Integration\n\nEmbed generated SVGs directly in your HTML:\n\n```html\n<!-- Option 1: Inline SVG -->\n<div class=\"arrow-container\">\n <!-- Paste SVG content here -->\n</div>\n\n<!-- Option 2: External file -->\n<img src=\"path/to/arrow.svg\" alt=\"Animated arrow\" />\n\n<!-- Option 3: CSS background -->\n<div style=\"background-image: url('path/to/arrow.svg')\"></div>\n```\n\n## Type Safety\n\nCaptain Arro includes full type annotations for excellent IDE support:\n\n```python\nfrom captain_arro import FLOW_DIRECTIONS, ANIMATION_TYPES\n\n# TypeScript-style literal types\ndirection: FLOW_DIRECTIONS = \"right\" # \u2705 Valid\ndirection: FLOW_DIRECTIONS = \"invalid\" # \u274c Type error\n\nanimation: ANIMATION_TYPES = \"ease-in-out\" # \u2705 Valid \nanimation: ANIMATION_TYPES = \"bounce\" # \u274c Type error\n```\n\n## Examples\n\nThe `examples/` directory contains comprehensive usage examples:\n\n```bash\n# Generate all example SVGs\npython examples/basic_usage.py\n\n# View examples\nls examples/output/\n```\n\nSee [`examples/README.md`](examples/README.md) for detailed descriptions of each example.\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=captain_arro\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack captain_arro tests examples\n\n# Sort imports \nisort captain_arro tests examples\n\n# Type checking\nmypy captain_arro\n\n# Linting\nflake8 captain_arro tests examples\n```\n\n## API Reference\n\n### Base Classes\n\n- `AnimatedArrowGeneratorBase` - Abstract base class for all generators\n\n### Generator Classes\n\n- `MovingFlowArrowGenerator` - Moving flow arrows\n- `SpotlightFlowArrowGenerator` - Spotlight flow arrows \n- `BouncingSpreadArrowGenerator` - Bouncing spread arrows\n- `SpotlightSpreadArrowGenerator` - Spotlight spread arrows\n\n### Type Definitions\n\n- `ANIMATION_TYPES` - Valid animation timing functions\n- `FLOW_DIRECTIONS` - Valid flow directions \n- `SPREAD_DIRECTIONS` - Valid spread directions\n\n## Browser Compatibility\n\nGenerated SVGs work in all modern browsers that support:\n- SVG animations (`animateTransform`)\n- CSS animations (`@keyframes`)\n- Linear gradients\n\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### v0.1.0\n\n- Initial release\n- Four arrow generator types\n- Full type safety\n- Comprehensive test suite\n- Documentation and examples\n\n---\n\nMade with \u2764\ufe0f and good vibes\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 helgeesch\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Animated SVG arrow generators for web interfaces",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/helgeesch/captain-arro/issues",
"Documentation": "https://github.com/helgeesch/captain-arro#readme",
"Homepage": "https://github.com/helgeesch/captain-arro",
"Repository": "https://github.com/helgeesch/captain-arro"
},
"split_keywords": [
"svg",
" animation",
" arrows",
" graphics",
" web",
" ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4ed19148e39f7a16571f5efcee8ecbc49072603304eb5d9b2d0c471744306650",
"md5": "de69baf59ba8395a650c0d2d8b5bd906",
"sha256": "f0cea6ee273098df86967425bc68006a9711215748ab8282cd7b811337cf9108"
},
"downloads": -1,
"filename": "captain_arro-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de69baf59ba8395a650c0d2d8b5bd906",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21703,
"upload_time": "2025-08-02T09:45:50",
"upload_time_iso_8601": "2025-08-02T09:45:50.028694Z",
"url": "https://files.pythonhosted.org/packages/4e/d1/9148e39f7a16571f5efcee8ecbc49072603304eb5d9b2d0c471744306650/captain_arro-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ccdb55ccca1fac768170ec0fb7f503e863967375abbfd9db731e314f7fa0233",
"md5": "a2b47467eca49a90abde723c09937d0d",
"sha256": "cef8cb1f0ed354049135c940874e3f4226ae53bf8a9e157863232c6cc5cbab22"
},
"downloads": -1,
"filename": "captain_arro-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a2b47467eca49a90abde723c09937d0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26405,
"upload_time": "2025-08-02T09:45:51",
"upload_time_iso_8601": "2025-08-02T09:45:51.437849Z",
"url": "https://files.pythonhosted.org/packages/0c/cd/b55ccca1fac768170ec0fb7f503e863967375abbfd9db731e314f7fa0233/captain_arro-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 09:45:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "helgeesch",
"github_project": "captain-arro",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "captain-arro"
}
