🚀 URL Shortener v2.0 - Professional Python Package

The codebase has been reorganized into a professional Python package structure following Flask best practices:

Url_Shortner_python/
├── 📁 url_shortener/              # Main Python package
│   ├── 📄 __init__.py            # Package initialization
│   ├── 📄 app.py                 # Flask application factory
│   ├── 📄 config.py              # Configuration management
│   ├── 📄 models.py              # Database models & operations
│   ├── 📄 services.py            # Business logic & services
│   ├── 📄 routes.py              # API routes & endpoints
│   ├── 📄 utils.py               # Utility functions
│   ├── 📁 templates/             # Jinja2 templates
│   └── 📁 static/                # Static files (CSS, JS)
├── 📁 tests/                     # Test suite
│   ├── 📄 __init__.py
│   └── 📁 unit/                  # Unit tests
│       └── 📄 test_url_shortener.py
├── 📄 run.py                     # CLI entry point
├── 📄 setup.py                   # Package setup configuration
├── 📄 requirements.txt           # Python dependencies
└── 📄 README.md                  # This file

• URLModel: Database operations for URL shortening
• RateLimitModel: Rate limiting management
• SQLite database with optimized indexes
• Comprehensive analytics tracking

• URLService: Core URL shortening business logic
• AnalyticsService: Advanced analytics processing
• Validation, rate limiting, and error handling
• Separation of business logic from Flask

• API Routes: RESTful API endpoints under /api/
• Web Routes: HTML templates and web interface
• Blueprint-based organization
• Comprehensive error handling

• DevelopmentConfig: Development environment settings
• ProductionConfig: Production environment settings
• TestingConfig: Testing environment settings
• Environment-based configuration management

• create_app(): Flask application factory pattern
• Blueprint registration
• Logging configuration
• Service initialization

1. Clone and setup

   git clone https://github.com/GrandmaEJ/api.git
   cd Url_Shortner_python

2. Install dependencies

   # Using pip
   pip install -r requirements.txt
   
   # Or using uv (recommended)
   uv add flask validators click

3. Initialize database

   python run.py init-db

4. Start the server

   python run.py run

5. Access the application

   • 🌐 Web Interface: http://localhost:8398
   • 🔗 API Base: http://localhost:8398/api
   • 📊 Health Check: http://localhost:8398/health

The application provides comprehensive CLI management commands:

# Start development server
python run.py run

# Start with custom options
python run.py run --host 0.0.0.0 --port 5000 --debug

# Use specific configuration
python run.py run --config production

# Initialize database
python run.py init-db

# Clean up expired URLs
python run.py cleanup-expired

# Run test suite
python run.py test

# View all available commands
python run.py --help

# View specific command help
python run.py run --help

• Base URL: http://localhost:8398
• API Version: v2.0
• Content-Type: application/json

POST /api/short
Content-Type: application/json

{
    "url": "https://example.com/very/long/url",
    "custom_id": "mycustom",        # Optional
    "title": "My Website",          # Optional
    "description": "Main website",  # Optional
    "expiry_days": 30               # Optional (default: 30)
}

POST /api/urls/bulk
Content-Type: application/json

{
    "urls": [
        "https://example.com",
        {"url": "https://google.com", "custom_id": "google"},
        {"url": "https://github.com", "title": "GitHub"}
    ]
}

GET /api/urls/<short_id>/analytics

GET /api/urls?limit=50&offset=0

GET /<short_id>  # Redirects to original URL

GET /health
Response: {"status": "healthy", "version": "2.0.0"}

GET /api/version
Response: {"version": "2.0.0", "status": "active"}

1. Navigate to http://localhost:8398
2. Enter your long URL
3. Optionally add custom ID, title, and description
4. Click "Shorten URL"
5. View result with copy and preview options

# Create short URL
curl -X POST http://localhost:8398/api/short \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "custom_id": "example"}'

# Bulk creation
curl -X POST http://localhost:8398/api/urls/bulk \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://site1.com", "https://site2.com"]}'

import requests

# Create short URL
response = requests.post('http://localhost:8398/api/short', json={
    'url': 'https://www.python.org/',
    'custom_id': 'python',
    'title': 'Python Official'
})
data = response.json()
print(f"Short link: {data['short_link']}")

The application includes a comprehensive test suite:

# Run all tests
python run.py test

# Run specific test file
python -m pytest tests/unit/test_url_shortener.py -v

1. Clone repository

   git clone <repository-url>
   cd Url_Shortner_python

2. Setup virtual environment

   # Using venv
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # or venv\Scripts\activate  # Windows
   
   # Using uv (recommended)
   uv venv
   source .venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt
   # or
   uv add flask validators click

4. Run tests

   python run.py test

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

# Install package
pip install url-shortener-v2

# Use CLI commands
url-shortener run --port 5000

# Database
DATABASE_PATH=url_shortener_v2.db

# Security
SECRET_KEY=your-secret-key
ADMIN_KEY=your-admin-key

# URLs
BASE_URL=https://your-domain.com
DEFAULT_EXPIRY_DAYS=30

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_DEFAULT_REQUESTS=30
RATE_LIMIT_BULK_REQUESTS=10

# Logging
LOG_LEVEL=INFO
LOG_FILE=url_shortener_v2.log

# Default configuration
DATABASE_PATH=url_shortener_v2.db
BASE_URL=http://localhost:8398
DEBUG=True
RATE_LIMIT_ENABLED=True

# Production configuration
SECRET_KEY=os.environ.get('SECRET_KEY')
BASE_URL=https://your-domain.com
DEBUG=False
RATE_LIMIT_ENABLED=True
RATE_LIMIT_DEFAULT_REQUESTS=20

• 🔗 Smart URL Shortening - Auto-generate or custom short URLs
• 📊 Real-time Analytics - Click tracking, browser analysis, referrer tracking
• ⚡ Bulk Operations - Shorten multiple URLs simultaneously
• 🛡️ Rate Limiting - Built-in request throttling
• 🎯 Custom Metadata - Support for titles, descriptions, and expiry
• 🔄 Auto-cleanup - Automatic expired URL management

• 🏭 Application Factory - Flask factory pattern for scalability
• 📦 Python Package - Professional package structure
• 🔧 CLI Tools - Comprehensive management commands
• 🧪 Test Suite - Unit tests with pytest
• 📋 Configuration - Environment-based configuration
• 📝 Documentation - Comprehensive API documentation
• 🎨 Modern UI - Responsive web interface

• URL Validation - Strict URL format and safety checking
• Rate Limiting - Per-IP request throttling
• Input Sanitization - XSS and injection prevention
• Secure Headers - Security-focused HTTP headers
• Admin Protection - Protected admin endpoints

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8398
CMD ["python", "run.py", "run", "--config", "production"]

[Unit]
Description=URL Shortener v2.0
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/url-shortener
ExecStart=/opt/url-shortener/venv/bin/python run.py run --config production
Restart=always

[Install]
WantedBy=multi-user.target

# Production environment
export FLASK_ENV=production
export DATABASE_PATH=/var/lib/url-shortener/url_shortener_v2.db
export BASE_URL=https://your-domain.com
export SECRET_KEY=your-production-secret-key

# Run with production config
python run.py run --config production

# Reset database
rm url_shortener_v2.db
python run.py init-db

# Check database
python run.py cleanup-expired

# Fix permissions
chmod +x run.py
chmod 664 *.db *.log

# Use different port
python run.py run --port 8399

# Enable debug logging
export LOG_LEVEL=DEBUG
python run.py run --debug

# Check application health
curl http://localhost:8398/health

# Check API version
curl http://localhost:8398/api/version

# Test database
python run.py init-db

pip install url-shortener-v2

git clone <repository>
cd Url_Shortner_python
pip install -e .

# Available commands
url-shortener run
url-shortener test
url-shortener init-db
url-shortener cleanup-expired

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run test suite: python run.py test
5. Submit pull request

• Python: Follow PEP 8
• Testing: Add tests for new features
• Documentation: Update README and docstrings
• Architecture: Maintain separation of concerns

• Include comprehensive tests
• Update documentation
• Follow existing code style
• Add changelog entry

This project is licensed under the MIT License - see the LICENSE file for details.

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Wiki: Project Wiki

• ⭐ Star this repository
• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features via GitHub Discussions
• 🤝 Contribute by submitting pull requests