## 1. Project Overview & Quickstart (trekhleb/learn-python)

## File: README.md

# Playground and Cheatsheet for Learning Python

> 🇺🇦 UKRAINE [IS BEING ATTACKED](https://war.ukraine.ua/) BY RUSSIAN ARMY. CIVILIANS ARE GETTING KILLED. RESIDENTIAL AREAS ARE GETTING BOMBED.
> - Help Ukraine via:
>   - [Serhiy Prytula Charity Foundation](https://prytulafoundation.org/en/)
>   - [Come Back Alive Charity Foundation](https://savelife.in.ua/en/donate-en/)
>   - [National Bank of Ukraine](https://bank.gov.ua/en/news/all/natsionalniy-bank-vidkriv-spetsrahunok-dlya-zboru-koshtiv-na-potrebi-armiyi)
> - More info on [war.ukraine.ua](https://war.ukraine.ua/) and [MFA of Ukraine](https://twitter.com/MFA_Ukraine)

<hr/>

[](https://travis-ci.org/trekhleb/learn-python)

> This is a collection of Python scripts that are split by [topics](#table-of-contents) and contain 
code examples with explanations, different use cases and links to further readings.

> _Read this in:_ [_Português_](README.pt-BR.md), [_Español_](README.es-ES.md), [_Traditional Chinese_](README.zh-TW.md), [_Українська_](README.uk-UA.md).

It is a **playground** because you may change or add the code to see how it works 
and [test it out](#testing-the-code) using assertions. It also allows you 
to [lint the code](#linting-the-code) you've wrote and check if it fits to Python code style guide.
Altogether it might make your learning process to be more interactive and it might help you to keep 
code quality pretty high from very beginning.

It is a **cheatsheet** because you may get back to these code examples once you want to recap the 
syntax of [standard Python statements and constructions](#table-of-contents). Also because the 
code is full of assertions you'll be able to see expected functions/statements output right away
without launching them.

> _You might also be interested in 🤖 [Interactive Machine Learning Experiments](https://github.com/trekhleb/machine-learning-experiments)_

## How to Use This Repository

Each Python script in this repository has the following structure:

```python
"""Lists  <--- Name of the topic here

# @see: https://www.learnpython.org/en/Lists  <-- Link to further readings goes here

Here might go more detailed explanation of the current topic (i.e. general info about Lists).
"""


def test_list_type():
    """Explanation of sub-topic goes here.
    
    Each file contains test functions that illustrate sub-topics (i.e. lists type, lists methods).
    """
    
    # Here is an example of how to build a list.  <-- Comments here explain the action
    squares = [1, 4, 9, 16, 25]
    
    # Lists can be indexed and sliced. 
    # Indexing returns the item.
    assert squares[0] == 1  # <-- Assertions here illustrate the result.
    # Slicing returns a new list.
    assert squares[-3:] == [9, 16, 25]  # <-- Assertions here illustrate the result.
```

So normally you might want to do the following:

- [Find the topic](#table-of-contents) you want to learn or recap.
- Read comments and/or documentation that is linked in each script's docstring (as in example above). 
- Look at code examples and assertions to see usage examples and expected output.
- Change code or add new assertions to see how things work.
- [Run tests](#testing-the-code) and [lint the code](#linting-the-code) to see if it work and is 
written correctly.

## Table of Contents

1. **Getting Started**
    - [What is Python](src/getting_started/what_is_python.md)
    - [Python Syntax](src/getting_started/python_syntax.md)
    - [Variables](src/getting_started/test_variables.py)
2. **Operators**
    - [Arithmetic Operators](src/operators/test_arithmetic.py) (`+`, `-`, `*`, `/`, `//`, `%`, `**`)
    - [Bitwise Operators](src/operators/test_bitwise.py) (`&`, `|`, `^`, `>>`, `<<`, `~`)
    - [Assignment Operators](src/operators/test_assigment.py) (`=`, `+=`, `-=`, `/=`, `//=` etc.)
    - [Comparison Operator](src/operators/test_comparison.py) (`==`, `!=`, `>`, `<`, `>=`, `<=`)
    - [Logical Operators](src/operators/test_logical.py) (`and`, `or`, `not`)
    - [Identity Operators](src/operators/test_identity.py) (`is`, `is not`)
    - [Membership Operators](src/operators/test_membership.py) (`in`, `not in`)
3. **Data Types**
    - [Numbers](src/data_types/test_numbers.py) (including booleans)
    - [Strings](src/data_types/test_strings.py) and their methods
    - [Lists](src/data_types/test_lists.py) and their methods (including list comprehensions)
    - [Tuples](src/data_types/test_tuples.py)
    - [Sets](src/data_types/test_sets.py) and their methods
    - [Dictionaries](src/data_types/test_dictionaries.py)
    - [Type Casting](src/data_types/test_type_casting.py)
4. **Control Flow**
    - [The `if` statement](src/control_flow/test_if.py)
    - [The `for` statement](src/control_flow/test_for.py) (and `range()` function)
    - [The `while` statement](src/control_flow/test_while.py)
    - [The `try` statements](src/control_flow/test_try.py)
    - [The `break` statement](src/control_flow/test_break.py)
    - [The `continue` statement](src/control_flow/test_continue.py)
5. **Functions**
    - [Function Definition](src/functions/test_function_definition.py) (`def` and `return` statements)
    - [Scopes of Variables Inside Functions](src/functions/test_function_scopes.py) (`global` and `nonlocal` statements)
    - [Default Argument Values](src/functions/test_function_default_arguments.py)
    - [Keyword Arguments](src/functions/test_function_keyword_arguments.py)
    - [Arbitrary Argument Lists](src/functions/test_function_arbitrary_arguments.py)
    - [Unpacking Argument Lists](src/functions/test_function_unpacking_arguments.py) (`*` and `**` statements)
    - [Lambda Expressions](src/functions/test_lambda_expressions.py) (`lambda` statement)
    - [Documentation Strings](src/functions/test_function_documentation_string.py)
    - [Function Annotations](src/functions/test_function_annotations.py)
    - [Function Decorators](src/functions/test_function_decorators.py)
6. **Classes**
    - [Class Definition](src/classes/test_class_definition.py) (`class` statement)
    - [Class Objects](src/classes/test_class_objects.py)
    - [Instance Objects](src/classes/test_instance_objects.py)
    - [Method Objects](src/classes/test_method_objects.py)
    - [Class and Instance Variables](src/classes/test_class_and_instance_variables.py)
    - [Inheritance](src/classes/test_inheritance.py)
    - [Multiple Inheritance](src/classes/test_multiple_inheritance.py)
7. **Modules**
    - [Modules](src/modules/test_modules.py) (`import` statement)
    - [Packages](src/modules/test_packages.py)
8. **Errors and Exceptions**
    - [Handling Exceptions](src/exceptions/test_handle_exceptions.py) (`try` statement)
    - [Raising Exceptions](src/exceptions/test_raise_exceptions.py) (`raise` statement)
9. **Files**
    - [Reading and Writing](src/files/test_file_reading.py) (`with` statement)
    - [Methods of File Objects](src/files/test_file_methods.py)
10. **Additions**
    - [The `pass` statement](src/additions/test_pass.py)
    - [Generators](src/additions/test_generators.py) (`yield` statement)
11. **Brief Tour of the Standard Libraries**
    - [Serialization](src/standard_libraries/test_json.py) (`json` library)
    - [File Wildcards](src/standard_libraries/test_glob.py) (`glob` library)
    - [String Pattern Matching](src/standard_libraries/test_re.py) (`re` library)
    - [Mathematics](src/standard_libraries/test_math.py) (`math`, `random`, `statistics` libraries)
    - [Dates and Times](src/standard_libraries/test_datetime.py) (`datetime` library)
    - [Data Compression](src/standard_libraries/test_zlib.py) (`zlib` library)
12. **User input**
    - [Terminal input](src/user_input/test_input.py) (`input` statement)

## Prerequisites

**Installing Python**

Make sure that you have [Python3 installed](https://realpython.com/installing-python/) on your machine.

You might want to use [venv](https://docs.python.org/3/library/venv.html) standard Python library
to create virtual environments and have Python, pip and all dependent packages to be installed and 
served from the local project directory to avoid messing with system wide packages and their 
versions.

Depending on your installation you might have access to Python3 interpreter either by
running `python` or `python3`. The same goes for pip package manager - it may be accessible either
by running `pip` or `pip3`.

You may check your Python version by running:

```bash
python --version
```

Note that in this repository whenever you see `python` it will be assumed that it is Python **3**.

**Installing dependencies**

Install all dependencies that are required for the project by running:

```bash
pip install -r requirements.txt
```

## Testing the Code

Tests are made using [pytest](https://docs.pytest.org/en/latest/) framework.

You may add new tests for yourself by adding files and functions with `test_` prefix
(i.e. `test_topic.py` with `def test_sub_topic()` function inside).

To run all the tests please execute the following command from the project root folder:

```bash
pytest
```

To run specific tests please execute:

```bash
pytest ./path/to/the/test_file.py
```

## Linting the Code

Linting is done using [pylint](http://pylint.pycqa.org/) and [flake8](http://flake8.pycqa.org/en/latest/) libraries.

### PyLint

To check if the code is written with respect
to [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide please run:

```bash
pylint ./src/
```

In case if linter will detect error (i.e. `missing-docstring`) you may want to read more about 
specific error by running:

```bash
pylint --help-msg=missing-docstring
```

[More about PyLint](http://pylint.pycqa.org/)

### Flake8

To check if the code is written with respect
to [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide please run:

```bash
flake8 ./src
```

Or if you want to have more detailed output you may run:

```bash
flake8 ./src --statistics --show-source --count
```

[More about Flake8](http://flake8.pycqa.org/en/latest/)

## Author

- [@trekhleb](https://trekhleb.dev)

---

## File: README.es-ES.md

# Playground y Cheatsheet para aprender Python

[](https://travis-ci.org/trekhleb/learn-python)

> Esta es una colección de scripts de Python divididos en [categorías](#contenido) que contienen
ejemplos de código con sus explicaciones, diferentes usos y links a recursos adicionales.

> _Lee esto en:_ [_Inglés_](README.md), [_Portugués_](README.pt-BR.md), [_Traditional Chinese_](README.zh-TW.md), [_Українська_](README.uk-UA.md).

Es un **playground** ya que puedes cambiar o añadir cosas al código para ver
cómo funciona y [probarlo](#probando-el-código) usando aserciones. También puedes
[revisar el código](#revisando-el-código) que has escrito y averiguar si está acorde con
la guía de estilos de Python. Todo esto, en conjunto, puede hacer que tu proceso de aprendizaje
sea más interactivo y puede ayudarte a mantener la calidad del código muy alta desde el principio.

Es un **cheatsheet** porque puedes regresar y revisar los ejemplos de código para
fortalecer tus conocimientos sobre las [sentencias y contrucciones estándar de Python](#contenido).
Además, ya que el código tiene muchas aserciones, podrás ver el resultado de las funciones/sentencias en el mismo
código sin la necesidad de ejecutarlos.

> _También puede interesarte 🤖 [Interactive Machine Learning Experiments](https://github.com/trekhleb/machine-learning-experiments)_

## Cómo usar este repositorio

Cada script de Python en este repositorio sigue la estructura:

```python
"""Lists  <--- Nombre del tema

# @see: https://www.learnpython.org/en/Lists  <-- Link a recurso adicional

Aquí puede haber una explicación detallada del tema en concreto (ej: información general sobre listas).
"""


def test_list_type():
    """Explicación del sub-tema.
    
    Cada archivo contiene funciones de prueba que muestran sub-temas (ej: tipos de listas, métodos en listas).
    """
    
    # Este es un ejemplo de cómo construir una lista. <-- Estos comentarios explican el procedimiento
    squares = [1, 4, 9, 16, 25]
    
    # Las listas pueden ser indexadas y cortadas. 
    # Al indexar devuelve el item.
    assert squares[0] == 1  # <-- Estas aserciones muestran el resultado.
    # Al cortar devuelve una nueva lista.
    assert squares[-3:] == [9, 16, 25]  # <-- Estas aserciones muestran el resultado.
```

Normalmente, querrás hacer lo siguiente:

- [Encontrar el tema](#contenido) que quieres aprender o revisar.
- Leer los comentarios y/o la documentación que está escrita en cada docstring del script (toma como ejemplo el script de arriba).
- Ver los ejemplos de código y las aserciones para conocer diferentes maneras de usar el código y entender el resultado previsto.
- Cambiar el código o añadir nuevas aserciones para ver cómo funcionan las cosas.
- [Probar](#probando-el-código) y [revisar](#revisando-el-código) el código para ver si funciona y si está escrito
correctamente.

## Contenido

1. **Empezando**
    - [¿Qué es Python?](src/getting_started/what_is_python.md)
    - [Sintaxis de Python](src/getting_started/python_syntax.md)
    - [Variables](src/getting_started/test_variables.py)
2. **Operadores**
    - [Operadores aritméticos](src/operators/test_arithmetic.py) (`+`, `-`, `*`, `/`, `//`, `%`, `**`)
    - [Operadores Bitwise](src/operators/test_bitwise.py) (`&`, `|`, `^`, `>>`, `<<`, `~`)
    - [Operadores de atribución](src/operators/test_assigment.py) (`=`, `+=`, `-=`, `/=`, `//=` etc.)
    - [Operadores de comparación](src/operators/test_comparison.py) (`==`, `!=`, `>`, `<`, `>=`, `<=`)
    - [Operadores lógicos](src/operators/test_logical.py) (`and`, `or`, `not`)
    - [Operadores de identidad](src/operators/test_identity.py) (`is`, `is not`)
    - [Operadores de asociación](src/operators/test_membership.py) (`in`, `not in`)
3. **Tipos de datos**
    - [Números](src/data_types/test_numbers.py) (incluyendo booleans)
    - [Strings](src/data_types/test_strings.py) y sus métodos
    - [Listas](src/data_types/test_lists.py) y sus métodos (incluyendo comprensión de listas)
    - [Tuples](src/data_types/test_tuples.py)
    - [Sets](src/data_types/test_sets.py) y sus métodos
    - [Diccionarios](src/data_types/test_dictionaries.py)
    - [Tipo de casting](src/data_types/test_type_casting.py)
4. **Control de flujo**
    - [La sentencia `if`](src/control_flow/test_if.py)
    - [La sentencia `for`](src/control_flow/test_for.py) (y la función `range()`)
    - [La sentencia `while`](src/control_flow/test_while.py)
    - [La sentencia `try`](src/control_flow/test_try.py)
    - [La sentencia `break`](src/control_flow/test_break.py)
    - [La sentencia `continue`](src/control_flow/test_continue.py)
5. **Funciones**
    - [Definición de función](src/functions/test_function_definition.py) (sentencias `def` y `return`)
    - [Ámbito de variables dentro de funciones](src/functions/test_function_scopes.py) (sentencias `global` y `nonlocal`)
    - [Valores de argumento predeterminados](src/functions/test_function_default_arguments.py)
    - [Argumentos de palabras clave](src/functions/test_function_keyword_arguments.py)
    - [Listas de argumento arbitrario](src/functions/test_function_arbitrary_arguments.py)
    - [Listas de argumentos en funciones](src/functions/test_function_unpacking_arguments.py) (sentencias `*` y `**`)
    - [Expresiones Lambda](src/functions/test_lambda_expressions.py) (sentencia `lambda`)
    - [Strings de documentación](src/functions/test_function_documentation_string.py)
    - [Anotaciones en funciones](src/functions/test_function_annotations.py)
    - [Decoradores de funciones](src/functions/test_function_decorators.py)
6. **Clases**
    - [Definición de clase](src/classes/test_class_definition.py) (sentencia `class`)
    - [Objetos de clase](src/classes/test_class_objects.py)
    - [Objetos de instancia](src/classes/test_instance_objects.py)
    - [Métodos de objetos](src/classes/test_method_objects.py)
    - [Variables de clase y de instancia](src/classes/test_class_and_instance_variables.py)
    - [Herencia](src/classes/test_inheritance.py)
    - [Herencia múltiple](src/classes/test_multiple_inheritance.py)
7. **Módulos**
    - [Módulos](src/modules/test_modules.py) (sentencia `import`)
    - [Paquetes](src/modules/test_packages.py)
8. **Errores y excepciones**
    - [Controlando excepciones](src/exceptions/test_handle_exceptions.py) (sentencia `try`)
    - [Generando excepciones](src/exceptions/test_raise_exceptions.py) (sentencia `raise`) 
9. **Archivos**
    - [Leyendo y escribiendo](src/files/test_file_reading.py) (sentencia `with`)
    - [Métodos de objetos de archivo](src/files/test_file_methods.py)
10. **Adicionales**
    - [La sentencia `pass`](src/additions/test_pass.py)
    - [Generadores](src/additions/test_generators.py) (sentencia `yield`)
11. **Pequeño tour de las librerías estándar**
    - [Serialización](src/standard_libraries/test_json.py) (librería `json`)
    - [Parámetros en archivos](src/standard_libraries/test_glob.py) (librería `glob`)
    - [Expresiones regulares](src/standard_libraries/test_re.py) (librearía `re`)
    - [Matemática](src/standard_libraries/test_math.py) (librerías `math`, `random` y `statistics`)
    - [Fechas y horas](src/standard_libraries/test_datetime.py) (librería `datetime`)
    - [Compresión de datos](src/standard_libraries/test_zlib.py) (librearía `zlib`)

## Pre-requisitos

**Instalando Python**

Asegúrate de que tienes [Python3 instalado](https://realpython.com/installing-python/) en tu sistema.

Podrías utilizar la librería estándar [venv](https://docs.python.org/es/3/library/venv.html) para crear
entornos virtuales y tener Python, pip y todos los paquetes instalados en el directorio de tu
proyecto local para evitar cometer errores con paquetes del sistema y sus versiones.

Dependiendo de la instalación, tendrás acceso a Python3 ejecutando `python` o `python3`. Lo mismo
aplica para el administrador de paquetes pip - puedes tener acceso a él ejecutando `pip` o `pip3`.

Puedes ver tu versión actual de Python ejecutando:

```bash
python --version
```

Ten en cuenta que cuando leas `python` en este repositorio, se asume que es Python **3**.

**Instalando dependencias**

Instala todas las depencias requeridas para el proyecto ejecutando:

```bash
pip install -r requirements.txt
```

## Probando el código

Las pruebas son hechas usando el framework [pytest](https://docs.pytest.org/en/latest/).

Puedes añadir más pruebas por ti mismo añadiendo archivos y funciones con el prefijo `test_`
(ej: `test_topic.py` con la función `def test_sub_topic()` adentro).

Para ejecutar todas las pruebas, por favor escribe el siguiente comando desde el directorio
raíz del proyecto:

```bash
pytest
```

Para ejecutar diferentes pruebas escribe:

```bash
pytest ./path/to/the/test_file.py
```

## Revisando el código

La revisión del código está hecha usando las librerías [pylint](http://pylint.pycqa.org/) y [flake8](http://flake8.pycqa.org/en/latest/).

### PyLint

Para revisar si el código sigue la guía de estilos
[PEP 8](https://www.python.org/dev/peps/pep-0008/), por favor ejecuta:

```bash
pylint ./src/
```

En caso de que linter detecte un error (ej: `missing-docstring`), te recomiendo leer más sobre
el error concreto ejecutando:

```bash
pylint --help-msg=missing-docstring
```

[Más sobre PyLint](http://pylint.pycqa.org/)

### Flake8

Para revisar si el código sigue la guía de estilos
[PEP 8](https://www.python.org/dev/peps/pep-0008/), por favor ejecuta:

```bash
flake8 ./src
```

O, si quieres ver un output más detallado, ejecuta:

```bash
flake8 ./src --statistics --show-source --count
```

[Más sobre Flake8](http://flake8.pycqa.org/en/latest/)

## Apoya al proyecto

Puedes apoyar al proyecto a través de ❤️️ [GitHub](https://github.com/sponsors/trekhleb) o ❤️️ [Patreon](https://www.patreon.com/trekhleb).

---

## File: README.pt-BR.md

# Playground e Cheatsheet Para Aprender Python

[](https://travis-ci.org/trekhleb/learn-python)

> Essa é uma coleção de scripts Python dividida em [tópicos](#índice) que contém 
exemplos de código com explicações, diferentes usos e links para outras leituras.

> _Ler em:_ [_English_](README.md), [_Español_](README.es-ES.md), [_Traditional Chinese_](README.zh-TW.md), [_Українська_](README.uk-UA.md).

É um **playground** porque você pode fazer alterações no código para ver como ele se comporta,
além de [testá-lo](#testando-o-código) usando asserções. Também é possível 
[revisar o código](#revisando-o-código) que você escreveu automaticamente e verificar se ele se encaixa
no guia de estilo de código Python.
Isso tudo pode tornar seu processo de aprendizagem mais interativo e ajudar a manter a qualidade
do código bastante alta desde o início.

É um **cheatsheet** porque você pode voltar a esses exemplos de código quando quiser recapitular a sintaxe das 
[estruturas padrão do Python](#índice). O código está cheio de asserções, então você poderá ver o retorno das funções sem precisar executá-las.

> _Você pode se interessar também por 🤖 [Interactive Machine Learning Experiments](https://github.com/trekhleb/machine-learning-experiments)_

## Como Usar Esse Repositório

Nesse repositório, cada script Python possui a seguinte estrutura:

```python
"""Lists  <--- Nome do tópico

# @see: https://www.learnpython.org/en/Lists  <-- Link para outras leituras.

A seguir, uma explicação mais detalhada do tópico atual (ex, informações gerais sobre listas (Lists)).
"""


def test_list_type():
    """Explicação do subtópico.
    
    Cada arquivo contém funções de teste que ilustram subtópicos (ou seja, tipo de lista, métodos de lista).
    """
    
    # Here is an example of how to build a list.  <-- Comentários em inglês explicam a ação.
    squares = [1, 4, 9, 16, 25]
    
    # Lists can be indexed and sliced. 
    # Indexing returns the item.
    assert squares[0] == 1  # <-- As asserções ilustram o resultado.
    # Slicing returns a new list.
    assert squares[-3:] == [9, 16, 25]  # <-- As asserções ilustram o resultado.
```

Então você pode querer fazer o seguinte:

- [Encontrar o tópico](#índice) que deseja aprender ou recapitular.
- Ler os comentários e/ou a documentação vinculada em cada script (como no exemplo acima).
- Analisar os exemplos e asserções para ver exemplos de uso e saída esperada das funções.
- Alterar o código ou adicionar novas asserções para ver o que acontece.
- [Executar testes](#testando-o-código) e [revisar o código](#revisando-o-código) para ver se ele
funciona e para saber se está escrito corretamente. 

## Índice

1. **Começando**
    - [O que é Python](src/getting_started/what_is_python.md)
    - [Sintaxe Python](src/getting_started/python_syntax.md)
    - [Variáveis](src/getting_started/test_variables.py)
2. **Operadores**
    - [Operadores Aritméticos](src/operators/test_arithmetic.py) (`+`, `-`, `*`, `/`, `//`, `%`, `**`)
    - [Operadores Bitwise](src/operators/test_bitwise.py) (`&`, `|`, `^`, `>>`, `<<`, `~`)
    - [Operadores de Atribuição](src/operators/test_assigment.py) (`=`, `+=`, `-=`, `/=`, `//=` etc.)
    - [Operadores de Comparação](src/operators/test_comparison.py) (`==`, `!=`, `>`, `<`, `>=`, `<=`)
    - [Operadores Lógicos](src/operators/test_logical.py) (`and`, `or`, `not`)
    - [Operadores de Indentidade](src/operators/test_identity.py) (`is`, `is not`)
    - [Operadores de Associação](src/operators/test_membership.py) (`in`, `not in`)
3. **Tipos de Dados**
    - [Números](src/data_types/test_numbers.py) (incluindo boleanos)
    - [Strings](src/data_types/test_strings.py) e seus métodos
    - [Listas](src/data_types/test_lists.py) e seus métodos (incluindo lista de compreensões)
    - [Tuplas](src/data_types/test_tuples.py)
    - [Conjuntos](src/data_types/test_sets.py) e seus métodos
    - [Dicionários](src/data_types/test_dictionaries.py)
    - [Casting de Tipo](src/data_types/test_type_casting.py)
4. **Controles de Fluxo**
    - [A declaração `if`](src/control_flow/test_if.py)
    - [A declaração `for`](src/control_flow/test_for.py) (e a função `range()`)
    - [A declaração `while`](src/control_flow/test_while.py)
    - [A declaração `try`](src/control_flow/test_try.py)
    - [A declaração `break`](src/control_flow/test_break.py)
    - [A declaração `continue`](src/control_flow/test_continue.py)
5. **Funções**
    - [Definição de Função](src/functions/test_function_definition.py) (declaração `def` e `return`)
    - [Variáveis Dentro das Funções](src/functions/test_function_scopes.py) (declaração `global` e `nonlocal`)
    - [Valores Padrão de Argumentos](src/functions/test_function_default_arguments.py)
    - [Argumentos de palavras-chave](src/functions/test_function_keyword_arguments.py)
    - [Listas de Argumento Arbitrárias](src/functions/test_function_arbitrary_arguments.py)
    - [Desfazendo Lista de Argumentos](src/functions/test_function_unpacking_arguments.py) (declaração `*` e `**`)
    - [Expressões Lambda](src/functions/test_lambda_expressions.py) (declaração `lambda`)
    - [Documentação das Strings](src/functions/test_function_documentation_string.py)
    - [Função de Anotações](src/functions/test_function_annotations.py)
    - [Função de Decoradores](src/functions/test_function_decorators.py)
6. **Classes**
    - [Definição de Classe](src/classes/test_class_definition.py) (declaração `class`)
    - [Classes dos Objetos](src/classes/test_class_objects.py)
    - [Instância dos Objetos](src/classes/test_instance_objects.py)
    - [Métodos de Objetos](src/classes/test_method_objects.py)
    - [Variável de Classe e Instância](src/classes/test_class_and_instance_variables.py)
    - [Herança](src/classes/test_inheritance.py)
    - [Herança Múltipla](src/classes/test_multiple_inheritance.py)
7. **Módulos**
    - [Módulos](src/modules/test_modules.py) (declaração `import`)
    - [Pacotes](src/modules/test_packages.py)
8. **Erros e Exceções**
    - [Tratando Exceções](src/exceptions/test_handle_exceptions.py) (declaração `try`)
    - [Levantando Exceções](src/exceptions/test_raise_exceptions.py) (declaração `raise`) 
9. **Arquivos**
    - [Lendo e Escrevendo](src/files/test_file_reading.py) (declaração `with`)
    - [Métodos de Objetos de Arquivos](src/files/test_file_methods.py)
10. **Adicional**
    - [A declaração `pass`](src/additions/test_pass.py)
    - [Geradores](src/additions/test_generators.py) (declaração `yield`)
11. **Algumas Bibliotecas Padrão**
    - [Serialization](src/standard_libraries/test_json.py) (biblioteca `json`)
    - [File Wildcards](src/standard_libraries/test_glob.py) (biblioteca `glob`)
    - [String Pattern Matching](src/standard_libraries/test_re.py) (biblioteca `re`)
    - [Matemática](src/standard_libraries/test_math.py) (bibliotecas `math`, `random` e `statistics`)
    - [Tempo e Datas](src/standard_libraries/test_datetime.py) (biblioteca `datetime`)
    - [Comprimindo Dados](src/standard_libraries/test_zlib.py) (biblioteca `zlib`)

## Pré-requisitos

**Instalando o Python**

Certifique-se de ter o [Python3 instalado](https://realpython.com/installing-python/) em sua máquina.

Você pode usar a biblioteca padrão do Python [venv](https://docs.python.org/3/library/venv.html)
para criar ambientes virtuais e ter o Python, pip e todos os outros pacotes a serem instalados
 a partir do diretório local do projeto para evitar mexer com pacotes externos ou do sistema.

Dependendo da sua instalação, você pode ter acesso ao interpretador Python3 executando `python` ou `python3`. O mesmo vale para o gerenciador de pacotes pip, você pode acessá-lo executando `pip` ou `pip3`.

Você pode ver a versão do seu Python executando:

```bash
python --version
```

Observe que neste repositório sempre que você vê o `python`, será assumido que é o Python **3**.

**Instalando dependências**

Instale todas as dependências necessárias para o projeto executando:

```bash
pip install -r requirements.txt
```

## Testando o Código

Testes são feitos usando o framework [pytest](https://docs.pytest.org/en/latest/).

Você pode adicionar novos testes criando arquivos e funções com o prefixo `test_` 
(ex. `test_topic.py` com a função `def test_sub_topic()` dentro).

Para executar todos os testes, execute o seguinte comando na pasta raiz do projeto:

```bash
pytest
```

Para executar testes específicos, execute:

```bash
pytest ./path/to/the/test_file.py
```

## Revisando o Código

A revisão é feita usando as bibliotecas [pylint](http://pylint.pycqa.org/) e [flake8](http://flake8.pycqa.org/en/latest/).

### PyLint

Para verificar se o código está escrito de acordo com o guia de estilo 
do [PEP 8](https://www.python.org/dev/peps/pep-0008/), execute:

```bash
pylint ./src/
```

Caso o pylint detecte um erro (ex. `missing-docstring`), convém ler mais sobre erros específicos executando:

```bash
pylint --help-msg=missing-docstring
```

[Saber mais sobre PyLint](http://pylint.pycqa.org/)

### Flake8

Para verificar se o código está escrito de acordo com o guia de estilo 
do [PEP 8](https://www.python.org/dev/peps/pep-0008/), execute:

```bash
flake8 ./src
```

Ou, se você quiser uma saída mais detalhada, execute:

```bash
flake8 ./src --statistics --show-source --count
```

[Saber mais sobre Flake8](http://flake8.pycqa.org/en/latest/)

---

Traduzido por [vilmacio22](https://github.com/vilmacio22).

---

## File: README.zh-TW.md

# 學習 Python 的練習場（Playground）和速查表（Cheatsheet）

[](https://travis-ci.org/trekhleb/learn-python)

> 此專案依據 [目錄](#目錄) 分類收集了 Python 腳本，包含了程式碼範例及解釋、不同的使用情境以及衍伸閱讀連結。

> _閱讀英文原始版本:_ [_English_](README.md), [_Português_](README.pt-BR.md), [_Español_](README.es-ES.md), [_Українська_](README.uk-UA.md).

此專案名稱之所以叫做 **練習場（Playground）**，是因為您可以修改或是新增程式碼至範例中去觀察程式執行流程並使用斷言關鍵字（assert）來 [測試程式](#測試程式)。同時，此專案也使用了業界常用的工具來 [檢查程式碼](#檢查程式碼)，確保您所撰寫的程式碼符合官方建議的 Python 程式碼風格規範。

總而言之，此專案會使您的學習過程更具互動性，並幫助您從一開始學習的時候就使用高品質的程式碼。

此專案名稱之所以也包含了 **速查表（Cheatsheet）** 是因為您可以隨時透過此專案中的 [標準 Python 陳述式以及結構](#目錄) 回顧程式碼語法，也因為在此專案中的每個程式碼範例都使用了斷言來說明及教學，故您可以不用執行程式就看到函式/陳述式的預期輸出結果。

> 若對機器學習（Machine Learning）有興趣，可以參考專案原作者的另一個學習專案：🤖 [Interactive Machine Learning Experiments](https://github.com/trekhleb/machine-learning-experiments)

## 如何使用此專案儲存庫

在此專案儲存庫中的每一個 Python 腳本皆為以下結構：

```python
"""串列（Lists） <--- 此為主題名稱

# @詳見: https://www.learnpython.org/en/Lists <-- 此為延伸閱讀連結

此處可能會有針對此主題更多的詳細說明（例如：關於串列的基本使用方法）
"""

def test_list_type():
    """此處為子主題解釋

    每個檔案皆包含說明該子主題的測試函式（例如：串列型態、串列方法）
    """

    # 建立串列之範例 <-- 此行是解釋下一行程式碼動作之註解
    squares = [1, 4, 9, 16, 25]

    # 串列可以被索引（indexed）及切片（sliced）
    # 索引會回傳該索引位置之內容值
    assert squares[0] == 1 # <-- 利用斷言來呈現結果
    # 切片會回傳一個新的串列
    assert squares[-3:] == [9, 16, 25] # <-- 利用斷言來呈現結果
```

故您可以做以下動作：

- 找一個您想要學習或是回顧的 [主題](#目錄)。
- 閱讀註解及/或包含於腳本文件字串（docstring）中的延伸閱讀資料（如上述之程式碼範例）。
- 查看程式碼範例並利用斷言來展示使用範例及預期輸出。
- 修改程式碼或新增新的斷言來了解程式運作流程。
- [執行測試](#測試程式) 及 [檢查程式碼](#檢查程式碼) 來確認程式是否被正確撰寫及是否可以被正確執行。

## 目錄

1. **入門**
    - [Python 是什麼](src/getting_started/what_is_python.md)
    - [Python 語法](src/getting_started/python_syntax.md)
    - [變數](src/getting_started/test_variables.py)
2. **運算子**
    - [數學運算子](src/operators/test_arithmetic.py) (`+`, `-`, `*`, `/`, `//`, `%`, `**`)
    - [位元運算子](src/operators/test_bitwise.py) (`&`, `|`, `^`, `>>`, `<<`, `~`)
    - [指派運算子](src/operators/test_assigment.py) (`=`, `+=`, `-=`, `/=`, `//=` 等 ...)
    - [比較運算子](src/operators/test_comparison.py) (`==`, `!=`, `>`, `<`, `>=`, `<=`)
    - [邏輯運算子](src/operators/test_logical.py) (`and`, `or`, `not`)
    - [恆等運算子](src/operators/test_identity.py) (`is`, `is not`)
    - [成員存取運算子](src/operators/test_membership.py) (`in`, `not in`)
3. **資料類型**
    - [數字](src/data_types/test_numbers.py)（包含布林值）
    - [字串](src/data_types/test_strings.py) 及相關方法
    - [串列](src/data_types/test_lists.py) 及相關方法（包含列表構建）
    - [元組](src/data_types/test_tuples.py)
    - [集合](src/data_types/test_sets.py) 及相關方法
    - [字典](src/data_types/test_dictionaries.py)
    - [類型轉換](src/data_types/test_type_casting.py)
4. **流程控制**
    - [`if` 陳述式](src/control_flow/test_if.py)
    - [`for` 陳述式](src/control_flow/test_for.py) (以及 `range()` 函式)
    - [`while` 陳述式](src/control_flow/test_while.py)
    - [`try` 陳述式](src/control_flow/test_try.py)
    - [`break` 陳述式](src/control_flow/test_break.py)
    - [`continue` 陳述式](src/control_flow/test_continue.py)
5. **函式**
    - [函式定義](src/functions/test_function_definition.py)（`def` 以及 `return` 陳述式）
    - [函式內變數作用範圍](src/functions/test_function_scopes.py)（`global` 以及 `nonlocal` 陳述式）
    - [預設引數](src/functions/test_function_default_arguments.py)
    - [關鍵字引數](src/functions/test_function_keyword_arguments.py)
    - [任意引數串列](src/functions/test_function_arbitrary_arguments.py)
    - [拆解引數串列](src/functions/test_function_unpacking_arguments.py)（`*` 以及 `**` 陳述式）
    - [Lambda 表達式](src/functions/test_lambda_expressions.py) (`lambda` 陳述式)
    - [文件字串](src/functions/test_function_documentation_string.py)
    - [函式註釋](src/functions/test_function_annotations.py)
    - [函式裝飾器](src/functions/test_function_decorators.py)
6. **類別**
    - [類別定義](src/classes/test_class_definition.py) (`class` 陳述式)
    - [類別物件](src/classes/test_class_objects.py)
    - [物件實體](src/classes/test_instance_objects.py)
    - [物件方法](src/classes/test_method_objects.py)
    - [類別及實體變數](src/classes/test_class_and_instance_variables.py)
    - [繼承](src/classes/test_inheritance.py)
    - [多重繼承](src/classes/test_multiple_inheritance.py)
7. **模組**
    - [模組](src/modules/test_modules.py) (`import` 陳述式)
    - [套件](src/modules/test_packages.py)
8. **錯誤和例外**
    - [例外處理](src/exceptions/test_handle_exceptions.py) (`try` 陳述式)
    - [例外引發](src/exceptions/test_raise_exceptions.py) (`raise` 陳述式)
9. **檔案**
    - [讀取和寫入](src/files/test_file_reading.py) (`with` 陳述式)
    - [檔案物件方法](src/files/test_file_methods.py)
10. **附加內容**
    - [`pass` 陳述式](src/additions/test_pass.py)
    - [生成器](src/additions/test_generators.py) (`yield` 陳述式)
11. **標準函式庫簡介**
    - [串列化](src/standard_libraries/test_json.py) (`json` 函式庫)
    - [檔案萬用字元](src/standard_libraries/test_glob.py) (`glob` 函式庫)
    - [字串規則比對](src/standard_libraries/test_re.py) (`re` 函式庫)
    - [數學運算](src/standard_libraries/test_math.py) (`math`, `random`, `statistics` 函式庫)
    - [日期和時間](src/standard_libraries/test_datetime.py) (`datetime` 函式庫)
    - [資料壓縮](src/standard_libraries/test_zlib.py) (`zlib` 函式庫)

## 使用此專案必備條件

**安裝 Python**

確認您已安裝 [Python3](https://realpython.com/installing-python/) 在您的電腦上。

您可能會想要使用標準 Python 函式庫所提供的 [虛擬環境](https://docs.python.org/3/library/venv.html) 功能在專案目錄中建立虛擬環境來佈署 Python 程式、pip 程式以及安裝所有需要的套件，藉此來避免作業系統中 Python 版本及相依性的混亂。

根據您的安裝方法，您可能可以通過以下方式執行 Python 3 直譯器：執行 `python` 或 `python3` 命令。pip 套件管理器執行方式也是如此：執行 `pip` 或 `pip3`。

您可以使用以下命令來確認 Python 版本：

```bash
python --version
```

此專案儲存庫中的所有程式碼皆是基於 Python **3**。

**安裝相依性套件**

透過以下命令安裝此專案需要的相依性套件：

```bash
pip install -r requirements.txt
```

## 測試程式

此專案使用 [pytest](https://docs.pytest.org/en/latest/) 測試框架來執行程式碼測試。

您可以新增以 `test_` 為開頭的檔案/函式來新增測試。（例如：`test_topic.py` 檔案內有 `def test_sub_topic()` 測試函式）

請從專案根目錄下使用以下命令來執行所有測試：

```bash
pytest
```

您也可以使用以下命令執行特定測試：

```bash
pytest ./path/to/the/test_file.py
```

## 檢查程式碼

此專案使用 [pylint](http://pylint.pycqa.org/) 以及 [flake8](http://flake8.pycqa.org/en/latest/) 函式庫來執行程式碼檢查。

### PyLint

檢查撰寫之程式碼是否符合 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 風格規範，請執行以下命令：

```bash
pylint ./src/
```

若此檢查工具偵測到錯誤（例如：`missing-docstring`），您可以使用以下命令查看特定錯誤之詳細說明：

```bash
pylint --help-msg=missing-docstring
```

[更多關於 PyLint](http://pylint.pycqa.org/)

### Flake8

檢查撰寫之程式碼是否符合 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 風格規範，請執行以下命令：

```bash
flake8 . /src
```

若您希望得到更多詳細的輸出，您可以加上以下參數再執行此工具：

```bash
flake8 . /src --statistics --show-source --count
```

[更多關於 Flake8](http://flake8.pycqa.org/en/latest/)

## 支持此專案

您可以透過 ❤️️ [GitHub](https://github.com/sponsors/trekhleb) 或 ❤️️ [Patreon](https://www.patreon.com/trekhleb) 支持原作者專案

## 2. Official Technical Reference & Guides (trekhleb/trekhleb.github.io)

# trekhleb.dev

[](https://github.com/trekhleb/trekhleb.github.io/actions?query=workflow%3ACI+branch%3Amaster)

My personal [website](https://trekhleb.dev) with a list of my projects that help people learn and blog posts about life, web-development, and machine-learning.



## Development

The website is built on [Gatsby](https://www.gatsbyjs.com/). See the [Gatsby cheat-sheet](https://www.gatsbyjs.com/gatsby-cheat-sheet.pdf) for development hints.

### Running the project locally

Install proper version of Node:

```bash
nvm use
```

Install dependencies:

```bash
npm i
```

To run the project locally in development mode on [http://localhost:8000](http://localhost:8000):

```bash
npm run develop
```

View GraphiQL, an in-browser IDE, to explore your site's data and schema on [http://localhost:8000/___graphql](https://localhost:8000/___graphql)

To build the production version of the project:

```bash
npm run build
```

Serve the production build for testing on [http://localhost:9000](http://localhost:9000):

```bash
npm run serve
```

To do ESLint and Type checking:

```bash
npm run lint
npm run type
```

To fix the Lint errors run:

```bash
npm run lint -- --fix
```

### Working with icons

Use [react-icons.github.io](https://react-icons.github.io/react-icons) to search for available icons.

### Styling components

Use [tailwindcss.com](https://tailwindcss.com) to search for available CSS classes.

### Custom Domain Support

To serve the [trekhleb.github.io](https://trekhleb.github.io) web-site on a custom domain [trekhleb.dev](https://trekhleb.dev) make sure that the `public` branch has `CNAME` file in the root folder. For more details read [this](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site).