# Parso

> If you want to contribute anything to parso, just open an issue or pull request to discuss it. We welcome changes! Please check the`CONTRIBUTING.md`file in the repository first.

---

# Source: https://github.com/davidhalter/parso/blob/master/docs/docs/development.rst

# Development

If you want to contribute anything to parso, just open an issue or pull request to discuss it. We welcome changes! Please check the `CONTRIBUTING.md` file in the repository first.

## Deprecations Process

The deprecation process is as follows:

1. A deprecation is announced in the next major/minor release.
2. We wait either at least a year & at least two minor releases until we remove the deprecated functionality.

## Testing

The test suite depends on `pytest`:

```bash
pip install pytest
```

### Running Tests

To run the tests use the following:

```bash
pytest
```

### Testing a Specific Python Version

If you want to test only a specific Python version (e.g. Python 3.9), it's as easy as:

```bash
python3.9 -m pytest
```

### Continuous Integration

Tests are also run automatically on [GitHub Actions](https://github.com/davidhalter/parso/actions).

---

# Source: https://github.com/davidhalter/parso/blob/master/docs/docs/installation.rst

# Installation and Configuration

## The Preferred Way (pip)

On any system you can install parso directly from the Python package index using pip:

```bash
sudo pip install parso
```

## From Git

If you want to install the current development version (master branch):

```bash
sudo pip install -e git+https://github.com/davidhalter/parso.git#egg=parso
```

## Manual Installation from a Downloaded Package

> Note: This method is not recommended.

If you prefer not to use an automated package installer, you can [download](https://github.com/davidhalter/parso/archive/master.zip) a current copy of parso and install it manually.

To install it, navigate to the directory containing `setup.py` on your console and type:

```bash
sudo python setup.py install
```

---

# Source: https://github.com/davidhalter/parso/blob/master/docs/docs/parser-tree.rst

# Parser Tree

The parser tree is returned by calling `parso.Grammar.parse()`.

**Note:** Parso positions are always 1-based for lines and 0-based for columns. This means the first position in a file is (1, 0).

## Parser Tree Base Classes

Generally there are two types of classes you will deal with: `parso.tree.Leaf` and `parso.tree.BaseNode`.

### parso.tree.BaseNode

A `BaseNode` is a node that contains other nodes/leaves. It's the parent type for all other node classes.

**Common attributes and methods:**

- `children` (list): List of child nodes and leaves.
- `type` (str): The type of this node (e.g., 'file_input', 'simple_stmt').
- `start_pos` (tuple): A tuple `(line, column)` representing the start position.
- `end_pos` (tuple): A tuple `(line, column)` representing the end position.
- `parent` (BaseNode or None): The parent node, or `None` if this is the root.

**Methods:**

- `children` - List of child nodes/leaves.
- `get_code()` - Returns the code represented by this node as a string.
- `get_first_leaf()` - Returns the first leaf node in this tree.
- `get_last_leaf()` - Returns the last leaf node in this tree.
- `get_next_sibling()` - Returns the next sibling node.
- `get_previous_sibling()` - Returns the previous sibling node.

### parso.tree.Leaf

A `Leaf` is a terminal node in the parse tree that represents a single token (like an identifier, operator, or keyword).

**Common attributes:**

- `value` (str): The string content of this leaf.
- `type` (str): The type of this leaf (e.g., 'NAME', 'OP', 'NUMBER').
- `start_pos` (tuple): A tuple `(line, column)` representing the start position.
- `end_pos` (tuple): A tuple `(line, column)` representing the end position.
- `parent` (BaseNode or None): The parent node.

**Methods:**

- `get_code()` - Returns the code represented by this leaf as a string.
- `get_next_sibling()` - Returns the next sibling node.
- `get_previous_sibling()` - Returns the previous sibling node.

### parso.tree.NodeOrLeaf

All nodes and leaves have these methods/properties (this is the base class for both `BaseNode` and `Leaf`):

**Common methods:**

- `get_root_node()` - Returns the root node of the tree.
- `get_code()` - Returns the code represented by this node/leaf as a string.
- `get_first_leaf()` - Returns the first leaf node in this tree.
- `get_last_leaf()` - Returns the last leaf node in this tree.
- `get_next_sibling()` - Returns the next sibling node, or `None` if this is the last sibling.
- `get_previous_sibling()` - Returns the previous sibling node, or `None` if this is the first sibling.
- `get_next_leaf()` - Returns the next leaf in the entire tree.
- `get_previous_leaf()` - Returns the previous leaf in the entire tree.
- `search_ancestor(*types)` - Returns an ancestor with one of the given types, or `None`.

**Properties:**

- `parent` - The parent node.
- `type` - The type of the node/leaf.
- `start_pos` - A tuple `(line, column)` representing the start position (1-based line, 0-based column).
- `end_pos` - A tuple `(line, column)` representing the end position.

## Python Parser Tree

The Python-specific parser tree extends the base classes with additional node types.

### parso.python.tree

Python-specific tree nodes represent Python language constructs such as:

- `PythonNode` - A node representing a Python grammar rule.
- `PythonLeaf` - A leaf representing a Python token.
- `Name` - Represents a name/identifier.
- `Number` - Represents a numeric literal.
- `String` - Represents a string literal.
- `Operator` - Represents an operator.
- `Keyword` - Represents a keyword.

These classes extend the base `BaseNode` and `Leaf` classes with Python-specific functionality.

## Utility

### parso.tree.search_ancestor()

```python
parso.tree.search_ancestor(node, *types)
```

Returns an ancestor of the given node with one of the given types, or `None` if no such ancestor exists.

**Parameters:**
- `node` (NodeOrLeaf): The node to start searching from.
- `*types` (str): The types to search for.

**Returns:** A `NodeOrLeaf` with one of the given types, or `None`.

**Example:**

```python
>>> import parso
>>> module = parso.parse('x = 1')
>>> leaf = module.get_first_leaf()
>>> parso.tree.search_ancestor(leaf, 'file_input')
<Module: @1-1>
```

---

# Source: https://github.com/davidhalter/parso/blob/master/docs/docs/usage.rst

# Usage

Parso works around grammars. You can simply create Python grammars by calling `parso.load_grammar()`. Grammars (with a custom tokenizer and custom parser trees) can also be created by directly instantiating `parso.Grammar`. More information about the resulting objects can be found in the [parser tree documentation](./parser-tree.md).

The simplest way of using parso is without even loading a grammar (`parso.parse()`):

```python
>>> import parso
>>> parso.parse('foo + bar')
<Module: @1-1>
```

## Loading a Grammar

Typically if you want to work with one specific Python version, use:

```python
parso.load_grammar(version=None, path=None)
```

Loads and returns a grammar. The default version is the current Python version.

**Parameters:**
- `version` (str): A string in the format `'3.9'` or `'3.10'` that specifies the Python version for which you want to parse.
- `path` (str): If you have a custom grammar file, you can also supply it here.

## Grammar Methods

You will get back a grammar object that you can use to parse code and find issues in it:

### Grammar.parse()

```python
Grammar.parse(code, *, error_recovery=True, start_symbol=None, cache=True, diff_cache=True)
```

Parses the given code and returns the parse tree.

**Parameters:**
- `code` (str or bytes): The code you want to parse.
- `error_recovery` (bool): If `True` (default), returns error nodes for invalid syntax. If `False`, raises `ParseError` for invalid syntax.
- `start_symbol` (str): Specifies which grammar rule to parse. The default is to parse a module.
- `cache` (bool): Store the parse tree in RAM for this code.
- `diff_cache` (bool): Store the parse tree on disk for incremental parsing.

**Returns:** A `parso.tree.NodeOrLeaf` object representing the parse tree.

### Grammar.iter_errors()

```python
Grammar.iter_errors(node)
```

Given a `parso.tree.NodeOrLeaf`, returns a generator of `parso.normalizer.Issue` objects.

## Error Retrieval

Parso is able to find multiple errors in your source code. Iterating through those errors yields the following instances:

### parso.normalizer.Issue

**Attributes:**
- `code` (int): An integer that represents the error type.
- `message` (str): A string representation of the error message.
- `start_pos` (tuple): A tuple `(line, column)` representing where the error starts.

## Utility Functions

Parso also offers some utility functions that can be really useful:

### parso.parse()

```python
parso.parse(code, *, version=None, error_recovery=True, start_symbol=None, cache=True, diff_cache=True)
```

A shortcut for loading a grammar and parsing code in one call. Internally does `parso.load_grammar(version).parse(code, ...)`.

### parso.split_lines()

```python
parso.split_lines(code, keepends=False)
```

Splits strings on `\n` and `\r\n` only (not on `\r`).

### parso.python_bytes_to_unicode()

```python
parso.python_bytes_to_unicode(source)
```

Converts Python source code to unicode, handling encoding declarations and BOMs (Byte Order Marks) correctly.

## Used By

- [jedi](https://github.com/davidhalter/jedi) - Used by IPython and a lot of editor plugins.
- [mutmut](https://github.com/boxed/mutmut) - Mutation testing framework.