🔍 PyTubeSearch

🔥 A powerful Python package for searching YouTube content by keywords. 🔍

✨ Features

• 🎯 Keyword Search: Search YouTube videos, channels, playlists by keywords
• 📹 Video Details: Get comprehensive video information including metadata
• 📋 Playlist Support: Extract playlist contents and metadata
• 📺 Channel Information: Retrieve channel details and content
• 🩳 YouTube Shorts: Access YouTube Shorts content
• 📄 Pagination: Handle large result sets with next page functionality
• 🚀 Fast & Reliable: Built with httpx for high performance
• 🔧 Type Safe: Full Pydantic model support with type hints
• 🎛️ Flexible Options: Filter by content type (video, channel, playlist, movie)

📦 Installation

pip install pytubesearch

Development Installation

git clone https://github.com/Malith-Rukshan/PyTubeSearch.git
cd PyTubeSearch
pip install -e .

🚀 Quick Start

Basic Search

from pytubesearch import PyTubeSearch

# Initialize the client
client = PyTubeSearch()

# Search for videos
results = client.search("python programming")

# Display results
for item in results.items:
    print(f"Title: {item.title}")
    print(f"Channel: {item.channel_title}")
    print(f"Video ID: {item.id}")
    print("-" * 50)

# Close the client
client.close()

Using Context Manager

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    results = client.search("machine learning", limit=10)
    
    for video in results.items:
        if video.type == "video":
            print(f"📹 {video.title} by {video.channel_title}")

Advanced Search with Filters

from pytubesearch import PyTubeSearch, SearchOptions

with PyTubeSearch() as client:
    # Search only for videos
    video_options = [SearchOptions(type="video")]
    results = client.search("python tutorial", options=video_options, limit=5)
    
    # Search only for channels
    channel_options = [SearchOptions(type="channel")]
    channels = client.search("tech channels", options=channel_options, limit=3)
    
    # Search with playlists included
    playlist_results = client.search("programming courses", with_playlist=True)

Get Video Details

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get detailed video information
    video_details = client.get_video_details("dQw4w9WgXcQ")
    
    print(f"Title: {video_details.title}")
    print(f"Channel: {video_details.channel}")
    print(f"Description: {video_details.description}")
    print(f"Keywords: {video_details.keywords}")
    print(f"Is Live: {video_details.is_live}")
    
    # Get suggested videos
    for suggestion in video_details.suggestion:
        print(f"Suggested: {suggestion.title}")

Pagination

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get first page
    results = client.search("data science")
    
    # Process first page
    for item in results.items:
        print(f"Page 1: {item.title}")
    
    # Get next page
    if results.next_page.next_page_token:
        next_results = client.next_page(results.next_page)
        
        for item in next_results.items:
            print(f"Page 2: {item.title}")

Playlist Operations

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get playlist contents
    playlist = client.get_playlist_data("PLrAXtmRdnEQy9j4XPpPNJkr0bO8E4BcJj")
    
    print(f"Playlist has {len(playlist.items)} videos")
    
    for video in playlist.items:
        print(f"🎥 {video.title}")
        print(f"   Channel: {video.channel_title}")

Channel Information

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get channel information
    channel_data = client.get_channel_by_id("UC8butISFwT-Wl7EV0hUK0BQ")
    
    for tab in channel_data:
        print(f"Tab: {tab.title}")

YouTube Shorts

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get YouTube Shorts
    shorts = client.get_short_videos()
    
    for short in shorts:
        print(f"🩳 {short.title}")
        print(f"   ID: {short.id}")

Homepage Suggestions

from pytubesearch import PyTubeSearch

with PyTubeSearch() as client:
    # Get homepage suggestions
    suggestions = client.get_suggestions(limit=10)
    
    for video in suggestions:
        print(f"💡 {video.title}")
        print(f"   Channel: {video.channel_title}")

💡 More Examples: Check out the examples/ directory for additional usage patterns and advanced implementations.

📚 API Reference

PyTubeSearch Class

Methods

• search(keyword, with_playlist=False, limit=0, options=None): Search YouTube content
• next_page(next_page_data, with_playlist=False, limit=0): Get next page of results
• get_video_details(video_id): Get detailed video information
• get_playlist_data(playlist_id, limit=0): Get playlist contents
• get_channel_by_id(channel_id): Get channel information
• get_suggestions(limit=0): Get homepage suggestions
• get_short_videos(): Get YouTube Shorts

Models

• SearchResult: Contains search results and pagination data
• SearchItem: Individual search result item
• VideoDetails: Detailed video information
• PlaylistResult: Playlist contents and metadata
• ChannelResult: Channel information
• ShortVideo: YouTube Shorts data
• SearchOptions: Search filtering options

🛠️ Development Guide

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/Malith-Rukshan/PyTubeSearch.git
   cd PyTubeSearch
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install development dependencies:

   # Option 1: Using Makefile (recommended)
   make install-dev
   
   # Option 2: Manual installation
   pip install -e .
   pip install -r requirements/dev.txt
   pre-commit install
   

Development Commands

The project includes a Makefile with common development tasks:

# Install for development
make install-dev

# Run tests
make test

# Run all tests including integration tests
make test-all

# Format code
make format

# Run linting
make lint

# Type checking
make type-check

# Security checks
make security

# Run all checks
make check

# Clean build artifacts
make clean

# Build package
make build

# Upload to Test PyPI
make upload-test

Testing

The project uses pytest for testing with multiple test categories:

1. Unit Tests: Fast tests that don't require network access

   pytest tests/ -m "not integration"
   

2. Integration Tests: Tests that interact with real YouTube data

   pytest tests/ -m "integration"
   

3. All Tests with Coverage:

   pytest tests/ --cov=pytubesearch --cov-report=html
   

Code Quality Standards

• Code Formatting: Black with 100 character line length
• Import Sorting: isort with Black profile
• Linting: Flake8 with custom configuration
• Type Checking: mypy for static type analysis
• Security: Bandit and Safety for security checks

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality:

# Install pre-commit hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files

Project Structure

PyTubeSearch/
├── pytubesearch/           # Main package
│   ├── __init__.py        # Package initialization
│   ├── client.py          # Main client implementation
│   └── models.py          # Pydantic models
├── tests/                 # Test suite
│   ├── conftest.py        # Test configuration
│   ├── test_client.py     # Client tests
│   ├── test_models.py     # Model tests
│   └── test_integration.py # Integration tests
├── examples/              # Usage examples
├── requirements/          # Dependency management
│   ├── base.txt          # Core dependencies
│   ├── dev.txt           # Development dependencies
│   └── test.txt          # Testing dependencies
├── .github/workflows/     # CI/CD workflows
├── docs/                  # Documentation
└── ...                   # Configuration files

Contributing Guidelines

1. Fork the repository and create your feature branch:

   git checkout -b feature/amazing-feature
   

2. Make your changes following the code quality standards

3. Add tests for your changes:

   • Unit tests for new functionality
   • Integration tests if applicable
   • Ensure all tests pass

4. Update documentation if needed:

   • Update README.md for new features
   • Add docstrings to new functions/classes
   • Update examples if applicable

5. Run quality checks:

   make check  # Runs linting, type checking, and tests
   

6. Commit your changes:

   git commit -m "Add amazing feature"
   

7. Push to your fork and create a Pull Request

Release Process

1. Update version in pyproject.toml and __init__.py
2. Update CHANGELOG.md with new features and fixes
3. Create a git tag:

   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push origin v1.0.0
   

4. GitHub Actions will automatically build and publish to PyPI

Testing with Test PyPI

Before releasing to PyPI, test the package on Test PyPI:

# Build and upload to Test PyPI
make build
make upload-test

# Install from Test PyPI to test
pip install --index-url https://test.pypi.org/simple/ pytubesearch

Debugging

For debugging integration tests or development:

# Enable debug logging
export PYTUBESEARCH_DEBUG=1

# Run specific test with verbose output
pytest tests/test_integration.py::TestSearchIntegration::test_basic_search_integration -v -s

Dependencies Management

The project uses a multi-file requirements approach:

• requirements/base.txt: Core runtime dependencies
• requirements/dev.txt: Development tools and utilities
• requirements/test.txt: Testing framework and tools

To update dependencies:

1. Edit the appropriate requirements file
2. Test the changes locally
3. Update version constraints if needed

🔧 Configuration

Timeout Settings

from pytubesearch import PyTubeSearch

# Set custom timeout (default: 30 seconds)
client = PyTubeSearch(timeout=60.0)

Error Handling

from pytubesearch import PyTubeSearch, PyTubeSearchError

try:
    with PyTubeSearch() as client:
        results = client.search("programming")
except PyTubeSearchError as e:
    print(f"Search failed: {e}")

📋 Requirements

• Python 3.8+
• httpx >= 0.24.0
• pydantic >= 2.0.0

🛠️ Development

Setup Development Environment

git clone https://github.com/Malith-Rukshan/PyTubeSearch.git
cd PyTubeSearch
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Formatting

black pytubesearch/
isort pytubesearch/

Type Checking

mypy pytubesearch/

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

⚠️ Disclaimer

This package is for educational purposes only. Please respect YouTube's Terms of Service and robots.txt when using this package. The package author is not responsible for any misuse of this tool.

🙏 Acknowledgments

• YouTube for providing the platform
• The Python community for amazing tools and libraries

🌟 Support and Community

If you found this project helpful, please give it a ⭐ on GitHub. This helps more developers discover the project! 🫶

📬 Contact

If you have any questions, feedback, or just want to say hi, you can reach out to me:

• Email: hello@malith.dev
• GitHub: @Malith-Rukshan

🧑‍💻 Built with 💖 by Malith Rukshan