| Name | pymgflip JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A type-safe Python client for the Imgflip meme generation API |
| upload_time | 2025-08-12 19:03:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
api
client
imgflip
meme
meme-generator
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pymgflip
A type-safe Python client for the [Imgflip](https://imgflip.com) meme generation API.
## Features
- Full type hints and type safety
- Support for all Imgflip API endpoints
- Automatic handling of authentication
- Graceful handling of premium-only features
- Comprehensive error handling
- Easy to use interface
## Installation
```bash
pip install pymgflip
```
## Quick Start
```python
from pymgflip import Client
# Get popular meme templates (no auth required)
client = Client()
memes = client.get_memes()
for meme in memes[:5]:
print(f"{meme.name}: {meme.id}")
```
## Authentication
Most endpoints require authentication with your Imgflip account:
```python
from pymgflip import Client
client = Client(username="your_username", password="your_password")
# Create a meme
result = client.caption_image(
template_id="61579", # "One Does Not Simply" template
text0="One does not simply",
text1="Use the Imgflip API without pymgflip"
)
if result.success:
print(f"Meme created: {result.url}")
```
## API Endpoints
### Free Endpoints
#### `get_memes()` - No authentication required
Get popular meme templates:
```python
client = Client()
memes = client.get_memes()
```
#### `caption_image()` - Requires authentication
Add captions to a meme template:
```python
client = Client(username="...", password="...")
result = client.caption_image(
template_id="61579",
text0="Top text",
text1="Bottom text",
font="impact", # default
max_font_size=50,
)
```
### Premium Endpoints
These endpoints require a premium Imgflip account ($9.99/month):
#### `search_memes()`
Search for meme templates:
```python
memes = client.search_memes(query="drake", include_nsfw=False)
```
#### `caption_gif()`
Caption animated GIF templates:
```python
result = client.caption_gif(
template_id="gif_template_id",
boxes=[
{"text": "First frame text"},
{"text": "Second frame text"},
]
)
```
#### `automeme()`
Automatically generate a meme from text:
```python
result = client.automeme(text="When the code works on the first try")
```
#### `ai_meme()`
Generate memes using AI:
```python
result = client.ai_meme(
model="openai", # or "classic"
prefix_text="When you realize",
template_id="optional_specific_template"
)
```
## Error Handling
The library provides specific exceptions for different error cases:
```python
from pymgflip import Client
from pymgflip.exceptions import (
AuthenticationError,
PremiumRequiredError,
APIError,
NetworkError
)
client = Client(username="...", password="...")
try:
result = client.search_memes("drake")
except AuthenticationError:
print("Invalid username or password")
except PremiumRequiredError:
print("This feature requires a premium account")
except NetworkError:
print("Network connection failed")
except APIError as e:
print(f"API error: {e}")
```
## Premium Detection
The client automatically detects if an account has premium access:
```python
client = Client(username="...", password="...")
# Try to use a premium feature
try:
client.search_memes("test")
except PremiumRequiredError:
pass
# Check premium status
if client.is_premium is False:
print("Account does not have premium access")
```
## Advanced Usage
### Custom Text Boxes
For advanced meme layouts with custom positioned text:
```python
result = client.caption_image(
template_id="61579",
boxes=[
{
"text": "Custom text",
"x": 10,
"y": 10,
"width": 100,
"height": 25,
"color": "#ffffff",
"outline_color": "#000000"
}
]
)
```
### Remove Watermark (Premium)
```python
result = client.caption_image(
template_id="61579",
text0="Top text",
text1="Bottom text",
no_watermark=True # Premium only
)
```
### Context Manager
Use the client as a context manager for automatic cleanup:
```python
with Client(username="...", password="...") as client:
memes = client.get_memes()
# Client automatically closes connections when done
```
## Testing
Run tests with pytest:
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run unit tests
pytest
# Run integration tests (requires real API)
pytest -m integration
# Run with coverage
pytest --cov=pymgflip
```
## Environment Variables
For testing with real credentials:
```bash
export IMGFLIP_USERNAME="your_username"
export IMGFLIP_PASSWORD="your_password"
pytest tests/test_integration.py -m integration
```
## Requirements
- Python 3.8+
- httpx
- pydantic
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Links
- [Imgflip API Documentation](https://imgflip.com/api)
- [PyPI Package](https://pypi.org/project/pymgflip/)
- [GitHub Repository](https://github.com/yourusername/pymgflip)
Raw data
{
"_id": null,
"home_page": null,
"name": "pymgflip",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "api, client, imgflip, meme, meme-generator",
"author": null,
"author_email": "Joel Grus <joelgrus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/47/6648959691be13bab5daf28cfef343ebfc3f7ddae1e49947108c7368309c/pymgflip-0.1.1.tar.gz",
"platform": null,
"description": "# pymgflip\n\nA type-safe Python client for the [Imgflip](https://imgflip.com) meme generation API.\n\n## Features\n\n- Full type hints and type safety\n- Support for all Imgflip API endpoints\n- Automatic handling of authentication\n- Graceful handling of premium-only features \n- Comprehensive error handling\n- Easy to use interface\n\n## Installation\n\n```bash\npip install pymgflip\n```\n\n## Quick Start\n\n```python\nfrom pymgflip import Client\n\n# Get popular meme templates (no auth required)\nclient = Client()\nmemes = client.get_memes()\n\nfor meme in memes[:5]:\n print(f\"{meme.name}: {meme.id}\")\n```\n\n## Authentication\n\nMost endpoints require authentication with your Imgflip account:\n\n```python\nfrom pymgflip import Client\n\nclient = Client(username=\"your_username\", password=\"your_password\")\n\n# Create a meme\nresult = client.caption_image(\n template_id=\"61579\", # \"One Does Not Simply\" template\n text0=\"One does not simply\",\n text1=\"Use the Imgflip API without pymgflip\"\n)\n\nif result.success:\n print(f\"Meme created: {result.url}\")\n```\n\n## API Endpoints\n\n### Free Endpoints\n\n#### `get_memes()` - No authentication required\nGet popular meme templates:\n\n```python\nclient = Client()\nmemes = client.get_memes()\n```\n\n#### `caption_image()` - Requires authentication\nAdd captions to a meme template:\n\n```python\nclient = Client(username=\"...\", password=\"...\")\nresult = client.caption_image(\n template_id=\"61579\",\n text0=\"Top text\",\n text1=\"Bottom text\",\n font=\"impact\", # default\n max_font_size=50,\n)\n```\n\n### Premium Endpoints\n\nThese endpoints require a premium Imgflip account ($9.99/month):\n\n#### `search_memes()`\nSearch for meme templates:\n\n```python\nmemes = client.search_memes(query=\"drake\", include_nsfw=False)\n```\n\n#### `caption_gif()`\nCaption animated GIF templates:\n\n```python\nresult = client.caption_gif(\n template_id=\"gif_template_id\",\n boxes=[\n {\"text\": \"First frame text\"},\n {\"text\": \"Second frame text\"},\n ]\n)\n```\n\n#### `automeme()`\nAutomatically generate a meme from text:\n\n```python\nresult = client.automeme(text=\"When the code works on the first try\")\n```\n\n#### `ai_meme()`\nGenerate memes using AI:\n\n```python\nresult = client.ai_meme(\n model=\"openai\", # or \"classic\"\n prefix_text=\"When you realize\",\n template_id=\"optional_specific_template\"\n)\n```\n\n## Error Handling\n\nThe library provides specific exceptions for different error cases:\n\n```python\nfrom pymgflip import Client\nfrom pymgflip.exceptions import (\n AuthenticationError,\n PremiumRequiredError,\n APIError,\n NetworkError\n)\n\nclient = Client(username=\"...\", password=\"...\")\n\ntry:\n result = client.search_memes(\"drake\")\nexcept AuthenticationError:\n print(\"Invalid username or password\")\nexcept PremiumRequiredError:\n print(\"This feature requires a premium account\")\nexcept NetworkError:\n print(\"Network connection failed\")\nexcept APIError as e:\n print(f\"API error: {e}\")\n```\n\n## Premium Detection\n\nThe client automatically detects if an account has premium access:\n\n```python\nclient = Client(username=\"...\", password=\"...\")\n\n# Try to use a premium feature\ntry:\n client.search_memes(\"test\")\nexcept PremiumRequiredError:\n pass\n\n# Check premium status\nif client.is_premium is False:\n print(\"Account does not have premium access\")\n```\n\n## Advanced Usage\n\n### Custom Text Boxes\n\nFor advanced meme layouts with custom positioned text:\n\n```python\nresult = client.caption_image(\n template_id=\"61579\",\n boxes=[\n {\n \"text\": \"Custom text\",\n \"x\": 10,\n \"y\": 10,\n \"width\": 100,\n \"height\": 25,\n \"color\": \"#ffffff\",\n \"outline_color\": \"#000000\"\n }\n ]\n)\n```\n\n### Remove Watermark (Premium)\n\n```python\nresult = client.caption_image(\n template_id=\"61579\",\n text0=\"Top text\",\n text1=\"Bottom text\",\n no_watermark=True # Premium only\n)\n```\n\n### Context Manager\n\nUse the client as a context manager for automatic cleanup:\n\n```python\nwith Client(username=\"...\", password=\"...\") as client:\n memes = client.get_memes()\n # Client automatically closes connections when done\n```\n\n## Testing\n\nRun tests with pytest:\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run unit tests\npytest\n\n# Run integration tests (requires real API)\npytest -m integration\n\n# Run with coverage\npytest --cov=pymgflip\n```\n\n## Environment Variables\n\nFor testing with real credentials:\n\n```bash\nexport IMGFLIP_USERNAME=\"your_username\"\nexport IMGFLIP_PASSWORD=\"your_password\"\npytest tests/test_integration.py -m integration\n```\n\n## Requirements\n\n- Python 3.8+\n- httpx\n- pydantic\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Links\n\n- [Imgflip API Documentation](https://imgflip.com/api)\n- [PyPI Package](https://pypi.org/project/pymgflip/)\n- [GitHub Repository](https://github.com/yourusername/pymgflip)",
"bugtrack_url": null,
"license": "MIT",
"summary": "A type-safe Python client for the Imgflip meme generation API",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/joelgrus/pymgflip#readme",
"Homepage": "https://github.com/joelgrus/pymgflip",
"Issues": "https://github.com/joelgrus/pymgflip/issues",
"Repository": "https://github.com/joelgrus/pymgflip"
},
"split_keywords": [
"api",
" client",
" imgflip",
" meme",
" meme-generator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb7b05e2af1b9c5542052643357041647e99f49ee72c04f4262d14380d90f401",
"md5": "9b95509619cf98e6ec49a0f8b1f55cef",
"sha256": "a192bd2f89a821149028582d0dfd7d136fafe54f06b6b378a2fd855de2ef65da"
},
"downloads": -1,
"filename": "pymgflip-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b95509619cf98e6ec49a0f8b1f55cef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8572,
"upload_time": "2025-08-12T19:03:28",
"upload_time_iso_8601": "2025-08-12T19:03:28.173472Z",
"url": "https://files.pythonhosted.org/packages/cb/7b/05e2af1b9c5542052643357041647e99f49ee72c04f4262d14380d90f401/pymgflip-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d4476648959691be13bab5daf28cfef343ebfc3f7ddae1e49947108c7368309c",
"md5": "4614f5cc3cf428836dd0aa6afe8a5dfe",
"sha256": "370f654f3a7addacb76cf8ec3f6a524bee31269210babcca3c2b6fe6a315b50b"
},
"downloads": -1,
"filename": "pymgflip-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4614f5cc3cf428836dd0aa6afe8a5dfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 79090,
"upload_time": "2025-08-12T19:03:29",
"upload_time_iso_8601": "2025-08-12T19:03:29.572727Z",
"url": "https://files.pythonhosted.org/packages/d4/47/6648959691be13bab5daf28cfef343ebfc3f7ddae1e49947108c7368309c/pymgflip-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 19:03:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joelgrus",
"github_project": "pymgflip#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymgflip"
}
