diff --git a/docs/3. Refactoring/3.3. Entrypoints.md b/docs/3. Refactoring/3.3. Entrypoints.md index 5cbf98a..9546576 100644 --- a/docs/3. Refactoring/3.3. Entrypoints.md +++ b/docs/3. Refactoring/3.3. Entrypoints.md @@ -1 +1,103 @@ -# 3.3. Entrypoints \ No newline at end of file +# 3.3. Entrypoints + +## What are package entrypoints? + +Package entrypoints are mechanisms in Python packaging that facilitate the exposure of scripts and utilities to end users. Entrypoints streamline the process of integrating and utilizing the functionalities of a package, whether that be through command-line interfaces (CLI) or by other software packages. + +To elaborate, entrypoints are specified in a package's setup configuration, marking certain functions or classes to be directly accessible. This setup benefits both developers and users by simplifying access to a package's capabilities, improving interoperability among different software components, and enhancing the user experience by providing straightforward commands to execute tasks. + +## Why do I need to set up entrypoints? + +Entrypoints are essential for making specific functionalities of your package directly accessible from the command-line interface (CLI) or to other software. By setting up entrypoints, you allow users to execute components of your package directly from the CLI, streamlining operations like script execution, service initiation, or utility invocation. Additionally, entrypoints facilitate dynamic discovery and utilization of your package's functionalities by other software and frameworks, such as Apache Airflow, without the need for hard-coded paths or module names. This flexibility is particularly beneficial in complex, interconnected systems where adaptability and ease of use are paramount. + +## How do I create entrypoints with poetry? + +Creating entrypoints with Poetry involves specifying them in the `pyproject.toml` file under the `[tool.poetry.scripts]` section. This section outlines the command-line scripts that your package will make available: + +```toml +[tool.poetry.scripts] +bikes = 'bikes.scripts:main' +``` + +In this syntax, `bikes` represents the command users will enter in the CLI to activate your tool. The path `bikes.scripts:main` directs Poetry to execute the `main` function found in the `scripts` module of the `bikes` package. Upon installation, Poetry generates an executable script for this command, integrating your package's functionality seamlessly into the user's command-line environment, alongside other common utilities: + +```bash +$ poetry run bikes one two three +``` + +This snippet run the bikes entrypoint from the CLI and passes 3 positional arguments: one, two, and three. + +## How can I use this entrypoint in other software? + +Defining and installing a package with entrypoints enables other software to easily leverage these entrypoints. For example, within Apache Airflow, you can incorporate a task in a Directed Acyclic Graph (DAG) to execute one of your CLI tools as part of an automated workflow. By utilizing Airflow's `BashOperator` or `PythonOperator`, your package’s CLI tool can be invoked directly, facilitating seamless integration: + +```python +from airflow import DAG +from datetime import datetime, timedelta +from airflow.providers.databricks.operators.databricks import DatabricksSubmitRunNowOperator + +# Define default arguments for your DAG +default_args = {...} + +# Create a DAG instance +with DAG( + 'databricks_submit_run_example', + default_args=default_args, + description='An example DAG to submit a Databricks job', + schedule_interval='@daily', + catchup=False, +) as dag: + # Define a task to submit a job to Databricks + submit_databricks_job = DatabricksSubmitRunNowOperator( + task_id='main', + json={ + "python_wheel_task": { + "package_name": "bikes", + "entry_point": "bikes", + "parameters": [ "one", "two", "three" ], + }, + } + ) + + # Set task dependencies and order (if you have multiple tasks) + # In this simple example, there's only one task + submit_databricks_job +``` + +In this example, `submit_databricks_job` is a task that executes the `bikes` entrypoint. + +## How can I use this entrypoint from the command-line (CLI)? + +Once your Python package has been packaged with Poetry and a wheel file is generated, you can install and use the package directly from the command-line interface (CLI). Here are the steps to accomplish this: + +1. **Build your package:** Use Poetry to compile your project into a distributable format, such as a wheel file. This is done with the `poetry build` command, which generates the package files in the `dist/` directory. + +```bash +poetry build +``` + +2. **Install your package:** With the generated wheel file (`*.whl`), use `pip` to install your package into your Python environment. The `pip install` command looks for the wheel file in the `dist/` directory, matching the pattern `bikes*.whl`, which is the package file created by Poetry. + +```bash +pip install dist/bikes*.whl +``` + +3. **Run your package from the CLI:** After installation, you can invoke the package's entrypoint—defined in your `pyproject.toml` file—directly from the command line. In this case, the `bikes` command followed by any necessary arguments. If your entrypoint is designed to accept arguments, they can be passed directly after the command. Ensure the arguments are separated by spaces unless specified otherwise in your documentation or help command. + +```bash +bikes one two three +``` + +## Which should be the input or output of my entrypoint? + +**Inputs** for your entrypoint can vary based on the requirements and functionalities of your package but typically include: + +- **Configuration files (e.g., JSON, YAML, TOML):** These files can define essential settings, parameters, and options required for your tool or package to function. Configuration files are suited for static settings that remain constant across executions, such as environment settings or predefined operational parameters. +- **Command-line arguments (e.g., --verbose, --account):** These arguments provide a dynamic way for users to specify options, flags, and parameters at runtime, offering adaptability for different operational scenarios. + +**Outputs** from your entrypoint should be designed to provide valuable insights and effects, such as: + +- **Side effects:** The primary purpose of your tool or package, which could include data processing, report generation, or initiating other software processes. +- **Logging:** Detailed logs are crucial for debugging, monitoring, and understanding how your tool or package operates within larger systems or workflows. + +Careful design of your entrypoints' inputs and outputs ensures your package can be integrated and used efficiently across a wide range of environments and applications, maximizing its utility and effectiveness. \ No newline at end of file diff --git a/docs/3. Refactoring/3.4. Configurations.md b/docs/3. Refactoring/3.4. Configurations.md index 92b5663..d7fb4aa 100644 --- a/docs/3. Refactoring/3.4. Configurations.md +++ b/docs/3. Refactoring/3.4. Configurations.md @@ -2,59 +2,82 @@ ## What are configurations? -Configurations are sets of parameters or constants that are external to your program but are essential for its operation. They are not hard-coded but are passed to the program via different means such as: -- [Environment variables](https://en.wikipedia.org/wiki/Environment_variable) -- [Configuration files](https://en.wikipedia.org/wiki/Configuration_file) -- [Command-Line Interface (CLI) arguments](https://en.wikipedia.org/wiki/Command-line_interface#Arguments) - -For example, a configuration file in YAML format might look like this: +Configurations consist of parameters or constants for the operation of your program, externalized to allow flexibility and adaptability. Configurations can be provided through various means, such as environment variables, configuration files, or command-line interface (CLI) arguments. For instance, a YAML configuration file might look like this: ```yaml job: KIND: TrainingJob inputs: - KIND: ParquetDataset + KIND: ParquetReader path: data/inputs.parquet - target: - KIND: ParquetDataset - path: data/target.parquet - output_model: outputs/model.joblib + targets: + KIND: ParquetReader + path: data/targets.parquet ``` +This structure allows for easy adjustment of parameters like file paths or job kinds, facilitating the program's operation across diverse environments and use cases. + ## Why do I need to write configurations? -Configurations allow your code to be adaptable and flexible without needing to modify the source code for different environments or use cases. This approach aligns with the principle of separating code from its execution environment, thereby enhancing portability and ease of changes. It’s akin to customizing application settings without altering the application’s core codebase. +Configurations enhance your code's flexibility, making it adaptable to different environments and scenarios without source code modifications. This separation of code from its execution environment boosts portability and simplifies updates or changes, much like adjusting settings in an application without altering its core functionality. ## Which file format should I use for configurations? -Common formats for configuration files include [JSON](https://www.json.org/json-en.html), [TOML](https://toml.io/en/), and [YAML](https://yaml.org/). YAML is often preferred due to its human-readable format, support for comments, and simpler syntax compared to TOML. However, be cautious with YAML files as they can contain malicious structures; always [load them safely](https://pyyaml.org/wiki/PyYAMLDocumentation). +When choosing a format for configuration files, common options include JSON, TOML, and YAML. YAML is frequently preferred for its readability, ease of use, and ability to include comments, which can be particularly helpful for documentation and maintenance. However, it's essential to be aware of YAML's potential for loading malicious content; therefore, always opt for safe loading practices. ## How should I pass configuration files to my program? -Passing configuration files to your program is effectively done using the Command-Line Interface (CLI). For example: +Passing configuration files to your program typically utilizes the CLI, offering a straightforward method to integrate configurations with additional command options or flags. For example, executing a command like: ```bash -$ program defaults.yaml training.yaml +$ bikes defaults.yaml training.yaml --verbose ``` -CLI allows for easy integration of configuration files with other command options and flags, like verbose logging: +This example enables the combination of configuration files with verbosity options for more detailed logging. This flexibility is also extendable to configurations stored on cloud services, provided your application supports such paths. -```bash -$ program defaults.yaml training.yaml --verbose +## Which toolkit should I use to parse and load configurations? + +For handling configurations in Python, [OmegaConf](https://omegaconf.readthedocs.io/) offers a powerful solution with features like YAML loading, deep merging, variable interpolation, and read-only configurations. It's particularly suited for complex settings and hierarchical structures. Additionally, for applications involving cloud storage, [cloudpathlib](https://cloudpathlib.drivendata.org/stable/) facilitates direct loading from services like AWS, GCP, and Azure. + +Utilizing Pydantic for configuration validation ensures that your application behaves as expected by catching mismatches or errors in configuration files early in the process, thereby avoiding potential failures after long-running jobs. + +```python +import pydantic as pdt + +class TrainTestSplitter(pdt.BaseModel): + """Split a dataframe into a train and test set. + + Parameters: + shuffle (bool): shuffle the dataset. Default is False. + test_size (int | float): number/ratio for the test set. + random_state (int): random state for the splitter object. + """ + + shuffle: bool = False + test_size: int | float + random_state: int = 42 ``` -## Which toolkit should I use to parse and load configurations? +## When should I use environment variables instead of configurations files? + +Environment variables are more suitable for simple configurations or when dealing with sensitive information that shouldn't be stored in files, even though they lack the structure and type-safety of dedicated configuration files. They are universally supported and easily integrated but may become cumbersome for managing complex or numerous settings. + +```bash +$ MLFLOW_TRACKING_URI=./mlruns bikes one two three +``` -For parsing and loading configurations in Python, [OmegaConf](https://omegaconf.readthedocs.io/) is a robust choice. It supports [loading YAML](https://omegaconf.readthedocs.io/en/latest/usage.html#creating) from various sources, [deep merging](https://omegaconf.readthedocs.io/en/latest/usage.html#omegaconf-merge) of configurations, [variable interpolation](https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation), and setting configurations as [read-only](https://omegaconf.readthedocs.io/en/latest/usage.html#read-only-flag). Additionally, for cloud-based projects, [cloudpathlib](https://cloudpathlib.drivendata.org/stable/) is useful for loading configurations from cloud storage services like AWS, GCP, and Azure. +In this example, the `MLFLOW_TRACKING_URI` is passed as an environment variable to the `bikes` program, while the command also accepts 3 positional arguments: one, two, and three. ## What are the best practices for writing and loading configurations? -1. **Safe Loading**: Always use `yaml.safe_load()` when loading YAML files to avoid executing arbitrary code. -2. **File Handling**: Employ context managers (the `with` statement) for file operations to ensure files are properly opened and closed. -3. **Error Handling**: Robust error handling for file IO and YAML parsing is crucial, such as handling missing or corrupted files. -4. **Validate Schema**: Validate configuration files against a predefined schema to ensure the correct structure and types. -5. **Sensitive Data**: Never store sensitive data like passwords in plain text. Use environment variables or secure storage solutions instead. -6. **Default Values**: Provide defaults for optional configuration parameters to enhance flexibility. -7. **Comments**: Use comments in your YAML files to explain the purpose and usage of various configurations. -8. **Consistent Formatting**: Keep a consistent format in your configuration files for ease of reading and maintenance. -9. **Versioning**: Version your configuration file format, especially for larger projects where changes in configurations are frequent and significant. \ No newline at end of file +To ensure effective configuration management: + +- Always use `yaml.safe_load()` to prevent the execution of arbitrary code. +- Utilize context managers for handling files to ensure proper opening and closing. +- Implement robust error handling for I/O operations and parsing. +- Validate configurations against a schema to confirm correctness. +- Avoid storing sensitive information in plain text; instead, use secure mechanisms. +- Provide defaults for optional parameters to enhance usability. +- Document configurations with comments for clarity. +- Maintain a consistent format across configuration files for better readability. +- Consider versioning your configuration format to manage changes effectively in larger projects. \ No newline at end of file diff --git a/docs/3. Refactoring/3.5. Documentations.md b/docs/3. Refactoring/3.5. Documentations.md index 2fac54f..de2d9ea 100644 --- a/docs/3. Refactoring/3.5. Documentations.md +++ b/docs/3. Refactoring/3.5. Documentations.md @@ -1,60 +1,100 @@ # 3.5. Documentations -## What are documentations? +## What are software documentations? -Documentation in the context of software development refers to written text or illustrations that accompany a software project. This can include anything from detailed API documentation to high-level overviews, guides, and tutorials. Good documentation helps users and contributors understand how to use and contribute to a project. +Software documentation encompasses written text or illustrations that support a software project. It can range from comprehensive API documentation to high-level overviews, guides, and tutorials. Effective documentation plays a crucial role in assisting users and contributors by explaining how to utilize and contribute to a project, ensuring the software is accessible and maintainable. -### Types of Documentation: +## Why do I need to create documentations? -1. **API Documentation**: Detailed information about the functions, classes, return types, and arguments in your code. -2. **Developer Guides**: Instructions on how to set up and contribute to the project. -3. **User Manuals**: Guides for end-users on how to use the software. -4. **Tutorials**: Step-by-step guides to achieve specific tasks with the software. -5. **FAQs**: Answers to frequently asked questions. -6. **Release Notes**: Information about new features, bug fixes, and changes in new versions. +Documentation is pivotal for several reasons: -## Why do I need to create documentations? +- **Usability**: It aids users in understanding how to interact with your software, detailing accepted inputs and expected outputs. +- **Maintainability**: Documentation facilitates new contributors in navigating the codebase and contributing efficiently, such as guiding through the process of submitting a pull request. +- **Longevity**: Projects with thorough documentation are more likely to be adopted, maintained, and enhanced over time, thanks to resources like troubleshooting sections. +- **Quality Assurance**: The process of writing documentation can uncover design issues or bugs, much like explaining a problem aloud can lead to solutions (e.g., through a data glossary). + +High-quality documentation encourages the use of your software and is valued by your users, while poor documentation can hinder developer productivity and deter users from engaging with your solution. + +## How should I associate documentations to my code base? + +Documentation within Python code can be incorporated in three key places: + +- Module documentation: This should be placed at the top of your Python module to provide an overview. + +```python +"""Define trainable machine learning models.""" +``` + +- Function or method documentation: Use this to describe the purpose of functions or methods, their parameters, and return values. + +```python +def parse_file(path: str) -> Config: + """Parse a config file from a given path. -Creating documentation is essential for several reasons: + Args: + path (str): Path to the local config file. -- **Usability**: Helps users understand how to use your software. -- **Maintainability**: Makes it easier for new contributors to understand the codebase and contribute effectively. -- **Longevity**: Well-documented projects are more likely to be used, maintained, and improved over time. -- **Quality Assurance**: Writing documentation can sometimes reveal underlying design flaws or bugs, similar to how explaining a problem aloud can help you find a solution. + Returns: + Config: Parsed representation of the config file. + """ + return oc.OmegaConf.load(path) +``` -Testing your documentation is just as important as testing your code. Regularly review and update your documentation to ensure it remains accurate and useful. +- Class documentation: Here, you describe the purpose and parameters of a class. -## Which tool should I use to create documentations? +```python +class ParquetReader(Reader): + """Reads a dataframe from a parquet file. -There are several tools and formats for creating documentation: + Attributes: + path (str): The local path to the dataset. + """ + + path: str +``` + +Beyond in-code documentation, complementing it with external documentation (e.g., project organization guides or how to report a bug) is beneficial. + +## Which tool, format, and convention should I use to create documentations? + +For creating documentation, you have multiple tools, formats, and conventions at your disposal: - **Tools**: - - **MkDocs**: A fast and simple static site generator that's geared towards project documentation. Written in Python. - - **pdoc**: A library and command-line tool to auto-generate API documentation for Python projects. - - **Sphinx**: A tool that makes it easy to create intelligent and beautiful documentation. It's widely used in the Python community. + - **MkDocs**: A fast, simple static site generator designed for project documentation, built with Python. + - **pdoc**: A tool and library for auto-generating API documentation for Python projects, best for API docs. + - **Sphinx**: A robust tool for creating detailed and beautiful documentation, popular within the Python community, albeit with a steeper setup curve. - **Formats**: - - **Markdown**: Easy-to-write plain text format that converts to structurally valid HTML. Suitable for simpler documentation. - - **reStructuredText (reST)**: More feature-rich than Markdown, used extensively in the Python ecosystem, particularly with Sphinx. + - **Markdown**: A straightforward text format that converts to HTML, ideal for simpler docs. + - **reStructuredText (reST)**: Offers more features than Markdown, widely used in Python documentation, especially with Sphinx. -## How should I associate documentations to my code base? +- **Convention**: + - **Numpy Style**: Features a clear, structured format for documenting Python functions, classes, and modules, focusing on readability. + - **Google Style**: Known for its simplicity and ease of use in documenting Python code, emphasizing clarity and brevity. + - **reStructuredText**: Offers a comprehensive set of markup syntax and constructs, ideal for technical documentation that requires detailed structuring and cross-referencing. + +For best practices, choose a tool and format that align with your project's needs and complexity. Adopting a widely recognized convention can facilitate consistency and comprehension across your documentation. Generating a simple API documentation can be as simple as calling a tool like `pdoc` with an input and output directory: + +```bash +$ poetry run pdoc --docformat=google --output-directory=docs/ src/bikes +``` + +You can also use your IDE or some extensions like [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) to automate the documentation generation process. + +## Is there some frameworks for organizing good documentation? -Associating documentation with your codebase involves: +Diataxis is a framework that offers a systematic approach to crafting technical documentation, recognizing four distinct documentation needs: tutorials, how-to guides, technical references, and explanations. It suggests organizing documentation to align with these needs, ensuring users find the information they're looking for efficiently. -- **In-Code Documentation**: Use comments and docstrings to document your code directly within the source files. -- **External Documentation**: Maintain a separate documentation directory (e.g., `docs/`) in your project repository. This can be generated from your code with tools like Sphinx or MkDocs. -- **Version Control**: Keep your documentation under version control alongside your code. This ensures that changes in code and corresponding documentation are tracked together. -- **Hosting**: Use platforms like ReadTheDocs, GitHub Pages, or GitLab Pages to host your documentation so it's easily accessible to users. +![Diataxis quadrant](https://diataxis.fr/_images/diataxis.png) ## What are best practices for writing my project documentation? -1. **Clarity and Conciseness**: Write clear and concise documentation. Avoid unnecessary jargon and complex sentences. -2. **Consistent Style**: Use a consistent style and format across all your documentation. -3. **Keep It Updated**: Regularly update the documentation to reflect changes in the software. -4. **Use Examples**: Include examples to demonstrate how to use different parts of your software. -5. **Accessibility**: Ensure your documentation is accessible, including to those with disabilities. -6. **Feedback Loop**: Encourage feedback on your documentation and incorporate it to improve. -7. **Multilingual Support**: Consider providing documentation in multiple languages, if applicable. -8. **Searchable**: Make sure your documentation is easily searchable to quickly find relevant information. -9. **Versioning**: Provide documentation for multiple versions of your software if necessary. -10. **Testing Documentation**: Regularly test your documentation for accuracy, just as you would test your code. \ No newline at end of file +1. **Clarity and Conciseness**: Strive for clear, straightforward documentation, avoiding complex language or unnecessary technical jargon. +2. **Consistent Style**: Maintain a uniform style and format throughout all documentation to enhance readability. +3. **Keep It Updated**: Regularly revise documentation to reflect the latest changes and additions to your software. +4. **Use Examples**: Provide practical examples to illustrate how different parts of your software operate. +5. **Accessibility**: Ensure your documentation is accessible to all users, including those with disabilities. +6. **Feedback Loop**: Encourage and incorporate feedback on your documentation to continuously improve its quality. +7. **Multilingual Support**: If possible, offer documentation in multiple languages to cater to a wider audience. +8. **Searchable**: Implement search functionality to allow users to quickly locate relevant information within your documentation. +9. **Versioning**: If your software has multiple versions, provide corresponding documentation for each version. \ No newline at end of file diff --git a/docs/3. Refactoring/3.6. VS Code Workspace.md b/docs/3. Refactoring/3.6. VS Code Workspace.md index 906bf93..0df6e15 100644 --- a/docs/3. Refactoring/3.6. VS Code Workspace.md +++ b/docs/3. Refactoring/3.6. VS Code Workspace.md @@ -1,3 +1,71 @@ # 3.6. VS Code Workspace -vs-code \ No newline at end of file +## What are VS Code Workspaces? + +[VS Code Workspaces](https://code.visualstudio.com/docs/editor/workspaces) are powerful configurations that allow you to manage and work on multiple projects within Visual Studio Code efficiently. A workspace can include one or more folders that are related to a particular project or task. Workspaces in VS Code enable you to save your project's settings, debug configurations, and extensions separately from your global VS Code settings, providing a customized and consistent development environment across your team. + +## Why should I use VS Code Workspace? + +Using a VS Code Workspace offers several benefits: + +- **Shared Settings**: Workspaces allow you to define common settings across all developers working on the project, ensuring consistency in coding conventions and reducing setup time for new contributors. +- **Productivity**: They enable developers to quickly switch contexts between different projects, each with its own tailored settings and preferences, thus enhancing productivity and focus. +- **Customization**: Workspaces provide the flexibility to customize the development environment according to the specific needs of a project without affecting global settings, making it easier to work on projects with different requirements. + +## How should I create and open my VS Code Workspace? + +To create and open a VS Code Workspace: + +1. **Create a Workspace**: Open VS Code and go to `File` > `Save Workspace As...` to save your current folder as a workspace. Provide a name for your workspace file, which will have a `.code-workspace` extension. +2. **Add Folders**: You can add multiple project folders to your workspace by going to `File` > `Add Folder to Workspace...` This is useful for grouping related projects. +3. **Open a Workspace**: To open an existing workspace, go to `File` > `Open Workspace...` and select the `.code-workspace` file you wish to open. + +## Which configurations can I pass to my workspace configuration? + +VS Code Workspace configurations support [the same settings as user settings](https://code.visualstudio.com/docs/getstarted/settings) but apply only within the context of the workspace. These configurations can be specified in the `.code-workspace` file, allowing you to customize various aspects of your development environment. For example: + +```json +{ + "folders": [ + { + "path": "." + } + ], + "settings": { + "editor.formatOnSave": true, + "python.defaultInterpreterPath": ".venv/bin/python", + "python.testing.pytestEnabled": true, + "python.testing.pytestArgs": [ + "tests" + ], + "[python]": { + "editor.codeActionsOnSave": { + "source.organizeImports": true + }, + "editor.defaultFormatter": "charliermarsh.ruff", + } + }, + "extensions": { + "recommendations": [ + "charliermarsh.ruff", + "dchanco.vsc-invoke", + "ms-python.mypy-type-checker", + "ms-python.python", + "ms-python.vscode-pylance", + "redhat.vscode-yaml" + ] + } +} +``` + +This configuration example sets up a project with: + +- **Folders**: Defines the project folders included in the workspace. +- **Settings**: Customizes editor behavior, such as format on save, default Python interpreter path, and testing configurations specific to Python. +- **Extensions**: Recommends extensions beneficial for the project, promoting consistency across the development team. + +By tailoring workspace settings, you ensure that every team member has a consistent development environment, which can include specific code formatting rules, linter settings, and extensions that are automatically recommended upon opening the workspace. + +## How can I configure my VS Code User Settings to become more productive? + +This article from the MLOps Community: [How to configure VS Code for AI, ML and MLOps development in Python 🛠️️](https://mlops.community/how-to-configure-vs-code-for-ai-ml-and-mlops-development-in-python-%f0%9f%9b%a0%ef%b8%8f%ef%b8%8f/) provide a in-depth guide for configuring VS Code environments. It starts by listing extensions that augments your programming environment. Then, the article shares some settings and keybindings that enhances your development experience. Finally, it provides some tips and tricks to boost your coding efficiency with VS Code. \ No newline at end of file diff --git a/docs/3. Refactoring/index.md b/docs/3. Refactoring/index.md index 3b462df..5e38b98 100644 --- a/docs/3. Refactoring/index.md +++ b/docs/3. Refactoring/index.md @@ -1 +1,11 @@ -# 3. Refactoring \ No newline at end of file +# 3. Refactoring + +In this chapter, we'll explore key strategies for improving your Python codebase, making it more maintainable, scalable, and efficient. We'll also cover the pivotal transition from working in notebooks to structuring your code as a Python package—a crucial step for enhancing code quality and collaboration. From organizing your project into packages and modules, understanding programming paradigms, and setting up entry points, to managing configurations, documenting your work, and optimizing your development environment with VS Code, you'll learn practical tips to refine your Python projects. This guide is designed to help you streamline your coding process and ensure your projects are robust and easy to manage, regardless of their size. Let's dive into refining your Python skills and elevating your projects. + +- [3.0. Package](./3.0. Package.md) - Learn how to organize and structure your Python codebase effectively for better modularity and maintainability. +- [3.1. Modules](./3.1. Modules.md) - Dive into the organization of Python files into modules for cleaner, more scalable code. +- [3.2. Paradigms](./3.1. Modules.md) - Explore various programming paradigms (OOP, functional programming) and their applications in Python refactoring. +- [3.3. Entrypoints](./3.1. Modules.md) - Understand the significance of entry points in managing the execution flow of your Python applications. +- [3.4. Configurations](./3.1. Modules.md) - Master the art of externalizing configurations to make your Python projects more flexible and environment-agnostic. +- [3.5. Documentations](./3.1. Modules.md) - Emphasize the importance of thorough documentation to enhance code understandability and maintainability. +- [3.6. VS Code Workspace](./3.1. Modules.md) - Optimize your development environment using Visual Studio Code for Python refactoring and better productivity. \ No newline at end of file