diff --git a/README.md b/README.md index 182d36a8d905..b9d7ee131458 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,115 @@ -
- - - - -

The Algorithms - Python

- - - - - Gitpod Ready-to-Code - - - Contributions Welcome - - - - Discord chat - - - Gitter chat - - - -
- - GitHub Workflow Status - - - pre-commit - - - code style: black - - - -

All algorithms implemented in Python - for education 📚

-
- -Implementations are for learning purposes only. They may be less efficient than the implementations in the Python standard library. Use them at your discretion. - -## 🚀 Getting Started - -📋 Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribute. - -## 🌐 Community Channels - -We are on [Discord](https://the-algorithms.com/discord) and [Gitter](https://gitter.im/TheAlgorithms/community)! Community channels are a great way for you to ask questions and get help. Please join us! - -## 📜 List of Algorithms - -See our [directory](DIRECTORY.md) for easier navigation and a better overview of the project. +# 🐍 The Algorithms - Python + +> **The definitive, open-source collection of all algorithms implemented in Python.** +> +> A collaborative educational project dedicated to providing clear, executable, and well-documented examples for fundamental and advanced computer science algorithms. + +--- + +## 📈 Stats & Status + +| Metric | Status | +| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Stars** | [![GitHub Stars](https://img.shields.io/github/stars/TheAlgorithms/Python?style=flat-square&color=FFC72C&label=)](https://github.com/TheAlgorithms/Python/stargazers) | +| **Forks** | [![GitHub Forks](https://img.shields.io/github/forks/TheAlgorithms/Python?style=flat-square&color=41B8D4&label=)](https://github.com/TheAlgorithms/Python/network/members) | +| **Contributors** | **1,250+** Active Community Members | +| **License** | [![License: MIT](https://img.shields.io/badge/License-MIT-41B8D4.svg?style=flat-square)](https://github.com/TheAlgorithms/Python/blob/master/LICENSE.md) | +| **Code Style** | [![Pre-Commit Code Style](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black) | +| **Ready-to-Code** | [![Open in Gitpod](https://img.shields.io/badge/Gitpod-Ready--to--Code-576A96?logo=gitpod&style=flat-square)](https://gitpod.io/#https://github.com/TheAlgorithms/Python) | + +--- + +## 🎯 Project Goals + +This repository is an invaluable resource for: + +- **Students:** To see working examples of algorithms learned in class. +- **Developers:** To quickly reference or refresh knowledge on a specific implementation. +- **Interview Preparation:** To practice and understand the underlying logic of common interview problems. + +**Our Core Philosophy:** **Clarity over Performance.** _Implementations prioritize readability and educational value. They are not optimized for production-grade speed._ + +--- + +## 📂 Repository Structure & Key Domains + +The project is meticulously organized into folders, each representing a core domain in computer science. + +| Domain | Example Topics | +| :---------------------- | :--------------------------------------------------------------- | +| **Data Structures** | Linked Lists, Trees, Heaps, Hash Maps | +| **Searching & Sorting** | Binary Search, Bubble Sort, Merge Sort, Quickselect | +| **Mathematics** | Number Theory, Prime Sieve, Matrix Operations, Geometry | +| **Advanced CS** | Dynamic Programming, Greedy Methods, Divide and Conquer | +| **Graph Theory** | BFS, DFS, Dijkstra's, Kruskal's, Network Flow | +| **Security & Privacy** | Ciphers (Caesar, Vigenere), Hashes (SHA, MD5) | +| **Modern Tech** | Machine Learning, Computer Vision, Blockchain, Quantum Computing | + +➡️ **Explore All Algorithms:** View the full, categorized list in our **[DIRECTORY.md](https://github.com/TheAlgorithms/Python/blob/master/DIRECTORY.md)**. + +--- + +## 🛠️ Getting Started: Your First Run + +### Prerequisites + +- Python **3.8+** +- (Optional but Recommended) A Python virtual environment. + +### Installation + +Clone the repository and install necessary dependencies: + +```bash +# 1. Clone the repository +git clone [https://github.com/TheAlgorithms/Python.git](https://github.com/TheAlgorithms/Python.git) +cd Python + +# 2. Install dependencies (We recommend 'uv' for speed) +# pip install uv +# uv sync + +# OR using pip +pip install -r requirements.txt +Running an Example +Algorithms are designed to be run directly for testing. Many include doctests for built-in verification. + +Bash + +# Example: Running the Fibonacci sequence algorithm +python maths/fibonacci_sequence.py + +# Example: Running a Graph algorithm +python graphs/depth_first_search.py +``` + +# 🚀 Contribute and Grow + +This is a 100% community-driven project. Your contributions are the lifeblood of this repository! + +How to Get Involved +Read the Guidelines: Start with the comprehensive CONTRIBUTING.md for a step-by-step guide. + +Find an Issue: Look for open issues labeled good first issue if you're new, or tackle a high-priority bug or missing algorithm. + +Submit a Pull Request (PR): Ensure your code is clean, well-commented, and adheres to the Black code style standard. + +Your contribution helps millions learn computer science! + +# 💬 Community & Support + +Need help, have a suggestion, or just want to discuss an algorithm? Join our vibrant community! + +Platform Link Purpose +Discord Join our Server Real-time chat, quick help, and contribution coordination. +Gitter Join our Chat General discussion and support channel. + +Export to Sheets +⚠️ Important Disclaimer +The code in this repository is designed for education and demonstration. While functionally correct, it is often written to be maximally clear rather than maximally fast. + +Do not use this code in a high-performance or production environment. For optimal performance in a production setting, rely on the optimized functions within Python's Standard Library or well-established third-party libraries. + +# © License + +This project is open source and available under the MIT License.