| Name | smart-slugify JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | A lightweight Python library for converting text to URL-friendly slugs with full Unicode support and zero dependencies |
| upload_time | 2025-10-18 12:03:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
slugify
url
slug
unicode
transliteration
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Smart Slugify
A lightweight (0 dependency), smart Python library for converting text into URL-friendly slugs with Unicode support, accent normalization, and customizable options.
[](https://github.com/ali-hai-der/smart-slugify/actions/workflows/ci.yml)
[](https://badge.fury.io/py/smart-slugify)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Features
✨ **Smart Text Normalization**: Automatically handles Unicode characters and removes diacritics
🌍 **International Support**: Works seamlessly with non-ASCII characters (Chinese, Arabic, Cyrillic, etc.)
⚙️ **Customizable**: Configure separator, casing, and maximum length
🚀 **Fast & Lightweight**: No external dependencies, pure Python
🧪 **Well-Tested**: Comprehensive test suite included
## Installation
### Using pip
```bash
pip install smart-slugify
```
### From Source
```bash
git clone https://github.com/ali-hai-der/smart-slugify.git
cd smart-slugify
pip install -e .
```
## Quick Start
```python
from smart_slugify import slugify
# Basic usage
slugify("Hello World!")
# Output: 'hello-world'
# Handles Unicode and accents automatically
slugify("C'est déjà l'été!")
# Output: 'c-est-deja-l-ete'
```
## Usage Examples
### Basic Text Conversion
```python
from smart_slugify import slugify
# Simple text
slugify("Hello World!")
# 'hello-world'
# Multiple spaces and special characters
slugify("Hello World!!! How are you?")
# 'hello-world-how-are-you'
# Numbers are preserved
slugify("Python 3.11 Released!")
# 'python-3-11-released'
```
### Unicode and Accent Handling
Smart Slugify automatically normalizes Unicode characters and removes diacritics:
```python
# French
slugify("C'est déjà l'été!")
# 'c-est-deja-l-ete'
# Spanish
slugify("¿Cómo estás?")
# 'como-estas'
# Portuguese
slugify("São Paulo")
# 'sao-paulo'
# German
slugify("Über uns")
# 'uber-uns'
# Mixed content
slugify("Café au lait & crème brûlée")
# 'cafe-au-lait-creme-brulee'
```
### Custom Separators
Change the default separator from hyphen to any character:
```python
# Underscore separator
slugify("Hello World!", separator="_")
# 'hello_world'
# Dot separator
slugify("My Blog Post", separator=".")
# 'my.blog.post'
# No separator (empty string)
slugify("Hello World", separator="")
# 'helloworld'
```
### Case Sensitivity
Control whether the output should be lowercase:
```python
# Default: lowercase
slugify("Hello World")
# 'hello-world'
# Preserve original case
slugify("Hello World", lowercase=False)
# 'Hello-World'
# Mixed case with underscores
slugify("iPhone 15 Pro", lowercase=False, separator="_")
# 'iPhone_15_Pro'
```
### Maximum Length
Truncate slugs to a specific length:
```python
# Truncate at 10 characters
slugify("hello world example", max_length=10)
# 'hello-wor'
# Smart truncation removes trailing separators
slugify("hello-world-test", max_length=12)
# 'hello-world' (not 'hello-world-')
# Long URLs
slugify("This is a very long article title that needs to be shortened", max_length=30)
# 'this-is-a-very-long-article-t'
```
### Edge Cases
Smart Slugify handles edge cases gracefully:
```python
# Empty string
slugify("")
# ''
# None input
slugify(None)
# ''
# Only special characters
slugify("!!@@##$$")
# ''
# Leading/trailing spaces and separators
slugify(" Hello World ")
# 'hello-world'
```
### Real-World Examples
```python
# Blog post URL
title = "10 Tips for Better Python Code in 2024"
slug = slugify(title)
# '10-tips-for-better-python-code-in-2024'
url = f"https://myblog.com/posts/{slug}"
# Product slugs for e-commerce
product = "MacBook Pro 16\" (2024) - Space Gray"
product_slug = slugify(product)
# 'macbook-pro-16-2024-space-gray'
# User-friendly file names
filename = "My Résumé - Software Engineer.pdf"
safe_filename = slugify(filename, separator="_")
# 'my_resume_software_engineer_pdf'
# Category paths
category = "Fashion & Accessories / Women's Clothing"
category_path = slugify(category, separator="/")
# 'fashion-accessories/women-s-clothing'
```
## API Reference
### `slugify(text, lowercase=True, separator='-', max_length=None)`
Converts input text into a URL-friendly slug.
**Parameters:**
- `text` (str): The input text to slugify. Can be `None` (returns empty string).
- `lowercase` (bool, optional): Convert to lowercase. Default: `True`.
- `separator` (str, optional): Character to use as separator. Default: `'-'`.
- `max_length` (int, optional): Maximum length of the slug. Default: `None` (no limit).
**Returns:**
- `str`: The slugified text.
**Processing Steps:**
1. Normalizes Unicode to NFKD form
2. Removes diacritical marks (accents)
3. Converts to lowercase (if enabled)
4. Replaces non-alphanumeric characters with separator
5. Collapses multiple consecutive separators into one
6. Strips leading and trailing separators
7. Truncates to `max_length` (if specified)
8. Removes trailing separators after truncation
## Development
### Running Tests
```bash
# Install pytest if you haven't already
pip install pytest
# Run tests
pytest tests/
# Run with verbose output
pytest -v tests/
# Run with coverage
pip install pytest-cov
pytest --cov=smart_slugify tests/
```
### Project Structure
```
smart-slugify/
├── src/
│ └── smart_slugify/
│ ├── __init__.py
│ └── slugify.py
├── tests/
│ └── test_slugify.py
├── pyproject.toml
├── README.md
└── LICENSE
```
## Contributing
Contributions are welcome! Here's how you can help:
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request
Please make sure to:
- Add tests for new features
- Update documentation as needed
- Follow PEP 8 style guidelines
- Write clear commit messages
## Use Cases
- **Web Applications**: Generate SEO-friendly URLs for blog posts, articles, and pages
- **E-commerce**: Create readable product URLs
- **CMS Systems**: Auto-generate slugs from user-provided titles
- **File Management**: Convert file names to safe, filesystem-friendly names
- **APIs**: Create consistent, readable endpoint identifiers
- **Database Keys**: Generate human-readable unique identifiers
## Why Smart Slugify?
- **No Dependencies**: Pure Python implementation with no external packages
- **Unicode-First**: Properly handles international characters out of the box
- **Battle-Tested**: Based on best practices from popular slugify implementations
- **Flexible**: Customizable to fit your specific needs
- **Lightweight**: Minimal footprint, fast performance
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Haider Ali**
Email: malikhaider0567@gmail.com
## Acknowledgments
- Inspired by Django's `slugify` utility
- Unicode normalization based on Python's `unicodedata` module
## Changelog
### Version 0.1.0 (Initial Release)
- Basic slugification with Unicode support
- Configurable separator and casing
- Maximum length truncation
- Comprehensive test suite
---
**Star ⭐ this repository if you find it useful!**
Raw data
{
"_id": null,
"home_page": null,
"name": "smart-slugify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "slugify, url, slug, unicode, transliteration",
"author": null,
"author_email": "Haider Ali <malikhaider0567@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/96/9c/dbde4360a71015adab865bcc1ccffbdc2c73812e4d1f7c70444294305349/smart_slugify-0.1.2.tar.gz",
"platform": null,
"description": "# Smart Slugify\n\nA lightweight (0 dependency), smart Python library for converting text into URL-friendly slugs with Unicode support, accent normalization, and customizable options.\n\n[](https://github.com/ali-hai-der/smart-slugify/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/smart-slugify)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## Features\n\n\u2728 **Smart Text Normalization**: Automatically handles Unicode characters and removes diacritics \n\ud83c\udf0d **International Support**: Works seamlessly with non-ASCII characters (Chinese, Arabic, Cyrillic, etc.) \n\u2699\ufe0f **Customizable**: Configure separator, casing, and maximum length \n\ud83d\ude80 **Fast & Lightweight**: No external dependencies, pure Python \n\ud83e\uddea **Well-Tested**: Comprehensive test suite included \n\n## Installation\n\n### Using pip\n\n```bash\npip install smart-slugify\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/ali-hai-der/smart-slugify.git\ncd smart-slugify\npip install -e .\n```\n\n## Quick Start\n\n```python\nfrom smart_slugify import slugify\n\n# Basic usage\nslugify(\"Hello World!\")\n# Output: 'hello-world'\n\n# Handles Unicode and accents automatically\nslugify(\"C'est d\u00e9j\u00e0 l'\u00e9t\u00e9!\")\n# Output: 'c-est-deja-l-ete'\n```\n\n## Usage Examples\n\n### Basic Text Conversion\n\n```python\nfrom smart_slugify import slugify\n\n# Simple text\nslugify(\"Hello World!\")\n# 'hello-world'\n\n# Multiple spaces and special characters\nslugify(\"Hello World!!! How are you?\")\n# 'hello-world-how-are-you'\n\n# Numbers are preserved\nslugify(\"Python 3.11 Released!\")\n# 'python-3-11-released'\n```\n\n### Unicode and Accent Handling\n\nSmart Slugify automatically normalizes Unicode characters and removes diacritics:\n\n```python\n# French\nslugify(\"C'est d\u00e9j\u00e0 l'\u00e9t\u00e9!\")\n# 'c-est-deja-l-ete'\n\n# Spanish\nslugify(\"\u00bfC\u00f3mo est\u00e1s?\")\n# 'como-estas'\n\n# Portuguese\nslugify(\"S\u00e3o Paulo\")\n# 'sao-paulo'\n\n# German\nslugify(\"\u00dcber uns\")\n# 'uber-uns'\n\n# Mixed content\nslugify(\"Caf\u00e9 au lait & cr\u00e8me br\u00fbl\u00e9e\")\n# 'cafe-au-lait-creme-brulee'\n```\n\n### Custom Separators\n\nChange the default separator from hyphen to any character:\n\n```python\n# Underscore separator\nslugify(\"Hello World!\", separator=\"_\")\n# 'hello_world'\n\n# Dot separator\nslugify(\"My Blog Post\", separator=\".\")\n# 'my.blog.post'\n\n# No separator (empty string)\nslugify(\"Hello World\", separator=\"\")\n# 'helloworld'\n```\n\n### Case Sensitivity\n\nControl whether the output should be lowercase:\n\n```python\n# Default: lowercase\nslugify(\"Hello World\")\n# 'hello-world'\n\n# Preserve original case\nslugify(\"Hello World\", lowercase=False)\n# 'Hello-World'\n\n# Mixed case with underscores\nslugify(\"iPhone 15 Pro\", lowercase=False, separator=\"_\")\n# 'iPhone_15_Pro'\n```\n\n### Maximum Length\n\nTruncate slugs to a specific length:\n\n```python\n# Truncate at 10 characters\nslugify(\"hello world example\", max_length=10)\n# 'hello-wor'\n\n# Smart truncation removes trailing separators\nslugify(\"hello-world-test\", max_length=12)\n# 'hello-world' (not 'hello-world-')\n\n# Long URLs\nslugify(\"This is a very long article title that needs to be shortened\", max_length=30)\n# 'this-is-a-very-long-article-t'\n```\n\n### Edge Cases\n\nSmart Slugify handles edge cases gracefully:\n\n```python\n# Empty string\nslugify(\"\")\n# ''\n\n# None input\nslugify(None)\n# ''\n\n# Only special characters\nslugify(\"!!@@##$$\")\n# ''\n\n# Leading/trailing spaces and separators\nslugify(\" Hello World \")\n# 'hello-world'\n```\n\n### Real-World Examples\n\n```python\n# Blog post URL\ntitle = \"10 Tips for Better Python Code in 2024\"\nslug = slugify(title)\n# '10-tips-for-better-python-code-in-2024'\nurl = f\"https://myblog.com/posts/{slug}\"\n\n# Product slugs for e-commerce\nproduct = \"MacBook Pro 16\\\" (2024) - Space Gray\"\nproduct_slug = slugify(product)\n# 'macbook-pro-16-2024-space-gray'\n\n# User-friendly file names\nfilename = \"My R\u00e9sum\u00e9 - Software Engineer.pdf\"\nsafe_filename = slugify(filename, separator=\"_\")\n# 'my_resume_software_engineer_pdf'\n\n# Category paths\ncategory = \"Fashion & Accessories / Women's Clothing\"\ncategory_path = slugify(category, separator=\"/\")\n# 'fashion-accessories/women-s-clothing'\n```\n\n## API Reference\n\n### `slugify(text, lowercase=True, separator='-', max_length=None)`\n\nConverts input text into a URL-friendly slug.\n\n**Parameters:**\n\n- `text` (str): The input text to slugify. Can be `None` (returns empty string).\n- `lowercase` (bool, optional): Convert to lowercase. Default: `True`.\n- `separator` (str, optional): Character to use as separator. Default: `'-'`.\n- `max_length` (int, optional): Maximum length of the slug. Default: `None` (no limit).\n\n**Returns:**\n\n- `str`: The slugified text.\n\n**Processing Steps:**\n\n1. Normalizes Unicode to NFKD form\n2. Removes diacritical marks (accents)\n3. Converts to lowercase (if enabled)\n4. Replaces non-alphanumeric characters with separator\n5. Collapses multiple consecutive separators into one\n6. Strips leading and trailing separators\n7. Truncates to `max_length` (if specified)\n8. Removes trailing separators after truncation\n\n## Development\n\n### Running Tests\n\n```bash\n# Install pytest if you haven't already\npip install pytest\n\n# Run tests\npytest tests/\n\n# Run with verbose output\npytest -v tests/\n\n# Run with coverage\npip install pytest-cov\npytest --cov=smart_slugify tests/\n```\n\n### Project Structure\n\n```\nsmart-slugify/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 smart_slugify/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 slugify.py\n\u251c\u2500\u2500 tests/\n\u2502 \u2514\u2500\u2500 test_slugify.py\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 LICENSE\n```\n\n## Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\nPlease make sure to:\n- Add tests for new features\n- Update documentation as needed\n- Follow PEP 8 style guidelines\n- Write clear commit messages\n\n## Use Cases\n\n- **Web Applications**: Generate SEO-friendly URLs for blog posts, articles, and pages\n- **E-commerce**: Create readable product URLs\n- **CMS Systems**: Auto-generate slugs from user-provided titles\n- **File Management**: Convert file names to safe, filesystem-friendly names\n- **APIs**: Create consistent, readable endpoint identifiers\n- **Database Keys**: Generate human-readable unique identifiers\n\n## Why Smart Slugify?\n\n- **No Dependencies**: Pure Python implementation with no external packages\n- **Unicode-First**: Properly handles international characters out of the box\n- **Battle-Tested**: Based on best practices from popular slugify implementations\n- **Flexible**: Customizable to fit your specific needs\n- **Lightweight**: Minimal footprint, fast performance\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Haider Ali** \nEmail: malikhaider0567@gmail.com\n\n## Acknowledgments\n\n- Inspired by Django's `slugify` utility\n- Unicode normalization based on Python's `unicodedata` module\n\n## Changelog\n\n### Version 0.1.0 (Initial Release)\n- Basic slugification with Unicode support\n- Configurable separator and casing\n- Maximum length truncation\n- Comprehensive test suite\n\n---\n\n**Star \u2b50 this repository if you find it useful!**\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python library for converting text to URL-friendly slugs with full Unicode support and zero dependencies",
"version": "0.1.2",
"project_urls": {
"documentation": "https://github.com/ali-hai-der/smart-slugify",
"homepage": "https://github.com/ali-hai-der/smart-slugify",
"repository": "https://github.com/ali-hai-der/smart-slugify"
},
"split_keywords": [
"slugify",
" url",
" slug",
" unicode",
" transliteration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b1e5b94e637ddb7a0da174f750aa821e275b2b0ce55fd768f75d57588be7c5fc",
"md5": "6efc84195515d3516747b6ea7dd1ae27",
"sha256": "d7fca1778238a5235dadd345ef0b81dd2c8cf70a6c2d578589c7625d8f5d5dee"
},
"downloads": -1,
"filename": "smart_slugify-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6efc84195515d3516747b6ea7dd1ae27",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6251,
"upload_time": "2025-10-18T12:03:23",
"upload_time_iso_8601": "2025-10-18T12:03:23.149155Z",
"url": "https://files.pythonhosted.org/packages/b1/e5/b94e637ddb7a0da174f750aa821e275b2b0ce55fd768f75d57588be7c5fc/smart_slugify-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "969cdbde4360a71015adab865bcc1ccffbdc2c73812e4d1f7c70444294305349",
"md5": "c1afff5e445576c4bdf109ec9f27c2e0",
"sha256": "94e4c73ad617e0ab77210020ddda32696ddb1fe4c513d8f70645898688816207"
},
"downloads": -1,
"filename": "smart_slugify-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c1afff5e445576c4bdf109ec9f27c2e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6219,
"upload_time": "2025-10-18T12:03:23",
"upload_time_iso_8601": "2025-10-18T12:03:23.906097Z",
"url": "https://files.pythonhosted.org/packages/96/9c/dbde4360a71015adab865bcc1ccffbdc2c73812e4d1f7c70444294305349/smart_slugify-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 12:03:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ali-hai-der",
"github_project": "smart-slugify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smart-slugify"
}
