### Stream Process a File with StreamFileProcessor

Source: https://maha.readthedocs.io/en/latest/overview

This example demonstrates how to process a file in a streaming fashion using `StreamFileProcessor`. It shows initializing the processor with a file path, applying normalization and filtering methods, and preparing for processing and saving the output. The example uses a sample file included with the Maha library.

```python
>>> from pathlib import Path
>>> import maha
>>> # This is a sample file that comes with Maha.
>>> resource_path = Path(maha.__file__).parents[1] / "sample_data/surah_al-ala.txt"
>>> from maha.processors import StreamFileProcessor
>>> proc = StreamFileProcessor(resource_path)
>>> proc = proc.normalize(all=True).keep(arabic_letters=True).drop_empty_lines()
>>> # To start processing the file, run the following commented code.
>>> # proc.process_and_save(Path("output.txt"))
```

--------------------------------

### Install Maha Python Library using Pip

Source: https://maha.readthedocs.io/en/latest/installation

This command installs the Maha Python library using pip. Ensure you have Python and pip installed on your system. The package name is 'mahad' due to a naming conflict with an existing project on PyPI.

```bash
pip install mahad
```

--------------------------------

### Tip Directive Example

Source: https://maha.readthedocs.io/en/latest/contributing/admonitions

Demonstrates the usage of the 'tip' directive, commonly used in documentation to provide helpful suggestions. It takes content directly within its block.

```rst
.. tip::
   A tip

```

--------------------------------

### Python Docstring Formatting Guidelines

Source: https://maha.readthedocs.io/en/latest/contributing/docstring

Demonstrates the correct and incorrect ways to format docstrings in Python, emphasizing that the docstring should start on the same line as the opening quotes.

```python
def do_this():
    """This is correct.
    (...)
    """

def dont_do_this():
    """
    This is incorrect.
    (...)
    """

```

--------------------------------

### Example: Applying relativedelta to a datetime object

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/time/template/index

Illustrates the practical application of a relativedelta object by adding it to a datetime object. This example showcases how relative and absolute time components, along with weekday adjustments, affect the final datetime.

```python
from datetime import datetime
from dateutil.relativedelta import relativedelta, MO

dt = datetime(2018, 4, 9, 13, 37, 0)
delta = relativedelta(hours=25, day=1, weekday=MO(1))

print(dt + delta)
```

--------------------------------

### Extract Arabic Characters using Maha Parser

Source: https://maha.readthedocs.io/en/latest/overview

This example shows how to use the `parse` function from `maha.parsers.functions` to extract all Arabic characters from a given text. It includes the `arabic=True` and `include_space=True` parameters for precise extraction.

```python
from maha.parsers.functions import parse
sample_text = "أنا وأخي في المكتبةِ نَدرسُ برمجه Python "
parse(sample_text, arabic=True, include_space=True)
[Dimension(body=أنا وأخي في المكتبةِ نَدرسُ برمجه , value=أنا وأخي في المكتبةِ نَدرسُ برمجه , start=0, end=34, dimension_type=DimensionType.ARABIC)]
```

--------------------------------

### Process Arabic Text with TextProcessor

Source: https://maha.readthedocs.io/en/latest/overview

This example shows how to use `TextProcessor` to clean and normalize Arabic text. It demonstrates methods like `normalize` (with `alef=True`), `keep` (with `arabic_letters=True`), and `drop_empty_lines`. The processor can also extract unique characters from the text.

```python
>>> from maha.processors import TextProcessor
>>> sample_text = """
...  بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ
... الْحَمْدُ لِلَّهِ رَبِّ الْعَالَمِينَ
... الرَّحْمَنِ الرَّحِيمِ
... مَالِكِ يَوْمِ الدِّينِ
... إِيَّاكَ نَعْبُدُ وَإِيَّاكَ نَسْتَعِينُ
... اهدِنَا الصِّرَاطَ الْمُسْتَقِيمَ
... صِرَاطَ الَّذِينَ أَنْعَمْتَ عَلَيْهِمْ غَيْرِ الْمَغْضُوبِ عَلَيْهِمْ وَلاَ الضَّالِّينَ
... """
>>> processor = TextProcessor.from_text(sample_text, sep="\n")
>>> cleaned_text = (
...     processor.normalize(alef=True).keep(arabic_letters=True).drop_empty_lines().text
... )
>>> print(cleaned_text)
بسم الله الرحمن الرحيم
الحمد لله رب العالمين
الرحمن الرحيم
مالك يوم الدين
اياك نعبد واياك نستعين
اهدنا الصراط المستقيم
صراط الذين انعمت عليهم غير المغضوب عليهم ولا الضالين
>>> # To print the unique characters
>>> unique_char = processor.get(unique_characters=True)
>>> unique_char.sort()
>>> unique_char
[' ', 'ا', 'ب', 'ت', 'ح', 'د', 'ذ', 'ر', 'س', 'ص', 'ض', 'ط', 'ع', 'غ', 'ق', 'ك', 'ل', 'م', 'ن', 'ه', 'و', 'ي']
```

--------------------------------

### Attention Directive Example

Source: https://maha.readthedocs.io/en/latest/contributing/admonitions

Presents the 'attention' directive, similar to 'tip' but can be used for specific calls to attention. It accepts content within its block.

```rst
.. attention::
   A attention

```

--------------------------------

### Get Fractions of Unit Pattern (Python)

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/index

Generates a regular expression pattern to match fractions of a given unit. This function is useful for parsing quantities expressed as fractions in Arabic text.

```python
def get_fractions_of_unit_pattern(_unit_):
    """
    Returns the fractions of a unit pattern.

    Parameters:
        unit (_str_) – The unit pattern.

    Returns:
        Pattern for the fractions of the unit.
    Return type:
        str
    """
    pass
```

--------------------------------

### Wrap Pattern with Start and End Expressions in Python

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/common

This function wraps a given regular expression pattern with start and end expressions. It takes a pattern string as input and returns a modified pattern that includes the start and end expressions, ensuring that the pattern matches the entire input.

```python
def wrap_pattern(pattern: str) -> str:
    """Adds start and end expression to the pattern."""
    return EXPRESSION_START + pattern + EXPRESSION_END
```

--------------------------------

### Get Text Lines in Batches

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Returns a generator that yields lists of strings, where each list contains a specified number of lines. This is memory-efficient for large texts.

```python
for batch in processor.get_lines(n_lines=10):
    # Process each batch of 10 lines
    print(batch)
```

--------------------------------

### Normalize All Arabic Characters (excluding Alef)

Source: https://maha.readthedocs.io/en/latest/overview

This example utilizes the `normalize` function from `maha.cleaners.functions` to perform normalization on all character types except for Alef variations. The function takes the input text and uses `all=True` to normalize everything, while `alef=False` explicitly excludes Alef normalization.

```python
>>> from maha.cleaners.functions import normalize
>>> sample_text = "أنا وأخي علي في المكتبةِ نَطلعُ على موضوع البرمجه"
>>> normalize(sample_text, alef=False, all=True)
'أنا وأخي علي في المكتبهِ نَطلعُ علي موضوع البرمجه'
```

--------------------------------

### Warning Directive Example

Source: https://maha.readthedocs.io/en/latest/contributing/admonitions

Illustrates the 'warning' directive, employed to alert readers about potential issues or important considerations. Alternative directives like 'caution' or 'danger' can be used for higher severity.

```rst
.. warning::
   Some text pointing out something that people should be warned about.

```

--------------------------------

### Extract Arabic Hashtags and Mentions using Maha Parser

Source: https://maha.readthedocs.io/en/latest/overview

This example illustrates extracting both Arabic hashtags and mentions from a text using the `parse` function with `arabic_hashtags=True` and `mentions=True` parameters. The output distinguishes between extracted hashtags and mentions.

```python
from maha.parsers.functions import parse
sample_text = "#مها #maha @Maha @مها"
parse(sample_text, arabic_hashtags=True, mentions=True)
[Dimension(body=#مها, value=#مها, start=0, end=4, dimension_type=DimensionType.ARABIC_HASHTAGS), Dimension(body=@Maha, value=@Maha, start=11, end=16, dimension_type=DimensionType.MENTIONS), Dimension(body=@مها, value=@مها, start=17, end=21, dimension_type=DimensionType.MENTIONS)]
```

--------------------------------

### Wrap Pattern in Expression Boundaries (Python)

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/index

Adds start and end expression anchors to a given regular expression pattern. This ensures that the pattern matches a complete expression rather than a substring.

```python
def wrap_pattern(_pattern_):
    """
    Adds start and end expression to the pattern.

    Parameters:
        pattern (_str_) –

    Return type:
        str
    """
    pass
```

--------------------------------

### Parse Dimensions using Numbers to Text Conversion

Source: https://maha.readthedocs.io/en/latest/overview

This example demonstrates the compatibility of `numbers_to_text` with `parse_dimension` from `maha.parsers.functions`. The `numbers_to_text` function converts numbers to text, which is then parsed back into numerical values by `parse_dimension`, showcasing accurate conversion and retrieval.

```python
>>> from maha.cleaners.functions import numbers_to_text
>>> from maha.parsers.functions import parse_dimension
>>> parse_dimension(numbers_to_text("في المكتبة 152 كتاب"), numeral=True)[0].value
152
>>> parse_dimension(numbers_to_text("في المكتبة 152 كتاب", accusative=True), numeral=True)[
...     0
... ].value
152
>>> parse_dimension(
...     numbers_to_text("يقدر عدد سكان العالم حوالي 7.9 مليار خلال عام 2022"), numeral=True
... )[0].value
7900000000
>>> parse_dimension(numbers_to_text("1,111,111"), numeral=True)[0].value
1111111
>>> parse_dimension(numbers_to_text("0.5"), numeral=True)[0].value
0.5
>>> parse_dimension(numbers_to_text("0.0033"), numeral=True)[0].value
0.0033
>>> parse_dimension(numbers_to_text("101.00102"), numeral=True)[0].value
101.00102
```

--------------------------------

### Define Arabic 'From' Expression

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/common

Defines a simple regular expression to match the Arabic word 'من' (from). This is a basic but essential pattern for identifying origins or starting points.

```python
FROM = Expression(non_capturing_group("من"))

```

--------------------------------

### Define Arabic Expression Start Pattern

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/common

Creates a regular expression that matches the beginning of a rule expression in Arabic, considering word boundaries and specific preceding conjunctions like WAW or LAM. It uses positive lookbehind assertions to ensure correct matching context.

```python
EXPRESSION_START = Expression(
    positive_lookbehind("^", r"\W", r"\b", r"\b" + WAW, r"\b" + LAM)
)

""" Pattern that matches the start of a rule expression in Arabic """
```

--------------------------------

### Get Fractions of Unit Pattern (Python)

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/common/index

Generates a regular expression pattern to match fractions of a given unit. It takes a unit pattern string as input and returns a string representing the regex pattern for its fractions. This function is useful for parsing numerical expressions involving fractions in Arabic.

```python
def get_fractions_of_unit_pattern(_unit_):
    """
    Returns the fractions of a unit pattern.

    Parameters
    ----------
    unit : str
        The unit pattern.

    Returns
    -------
    str
        Pattern for the fractions of the unit.
    """
    pass
```

--------------------------------

### Get Fractions of Unit Pattern in Python

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/common

This function generates a regular expression pattern for matching fractions of a given unit in Arabic. It takes a unit string as input and returns a pattern that matches the fractions of that unit, such as third, quarter, and half.

```python
def get_fractions_of_unit_pattern(unit: str) -> str:
    """
    Returns the fractions of a unit pattern.

    Parameters
    ----------
    unit: str
        The unit pattern.

    Returns
    -------
    str
        Pattern for the fractions of the unit.
    """

    return non_capturing_group(
        spaced_patterns(unit, THREE_QUARTERS),
        spaced_patterns(unit, TWO_THIRDS),
        spaced_patterns(HALF, unit),
        spaced_patterns(THIRD, unit),
        spaced_patterns(QUARTER, unit),
    )
```

--------------------------------

### Create Rule to Extract Book Count from Text (Python)

Source: https://maha.readthedocs.io/en/latest/development/custom_dimension

This Python code snippet demonstrates how to create a custom dimension rule to extract the number of books from a given text. It utilizes `FunctionValue` to define the rule, combining `parse_numeral` for number evaluation and `spaced_patterns` to match a numeral followed by the word 'كتاب'. The example shows parsing sample text and retrieving the extracted numerical value.

```python
from maha.parsers.rules import RULE_NUMERAL
from maha.parsers.rules import spaced_patterns
from maha.parsers.rules.numeral.rule import parse_numeral
from maha.parsers.templates import FunctionValue

RULE_BOOK_NUMBER = FunctionValue(
    parse_numeral, spaced_patterns(RULE_NUMERAL, "كتاب"), pickle=False
)

sample_text = "في المكتبة مئة كتاب"
result = list(RULE_BOOK_NUMBER.parse(sample_text))[0]

print(result.value)
print(sample_text[result.start : result.end])
```

--------------------------------

### Build Documentation Locally (Make)

Source: https://maha.readthedocs.io/en/latest/contributing/guidelines

Builds the project's documentation locally using Make. This allows you to preview documentation changes and ensure there are no Sphinx errors before submitting a pull request.

```shell
make html

```

--------------------------------

### Define Start of Week Constant (Python)

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/time/constants

Defines the START_OF_WEEK constant using the SU.weekday attribute from the dateutil.relativedelta library. This constant is likely used to specify the starting day of the week in date-related operations within the maha.parsers.rules.time module.

```python
from dateutil.relativedelta import SU


[docs]START_OF_WEEK = SU.weekday
```

--------------------------------

### Define Arabic Start Of Rub El Hizb Symbol

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/constants/index

Defines a constant for the Arabic 'Start of Rub el Hizb' symbol. This marker is used in Quranic text to divide the text into Hizbs (portions). No external dependencies are required.

```python
HIZB_START = "۞"
```

--------------------------------

### Initialize FileProcessor

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Initializes a FileProcessor to process text directly from a file. It handles file existence and emptiness checks.

```python
from pathlib import Path

file_path = Path("my_document.txt")
file_processor = FileProcessor(file_path)
```

--------------------------------

### Remove mentions from text

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/remove_fn/index

This function removes mentions (typically starting with @) from the given text.

```python
from maha.cleaners.functions import remove_mentions
text = "Hello @user1, check this out!"
remove_mentions(text)
'Hello , check this out!'
```

--------------------------------

### Initialize FileProcessor for File Stream Input

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Initializes a processor for handling file stream input. It takes the file path and encoding as parameters. Raises FileNotFoundError if the specified file does not exist. This is a class constructor.

```python
class StreamFileProcessor:
    def __init__(self, path, encoding='utf8'):
        """
        For processing file stream input.

        Parameters
            path (Union[str, pathlib.Path]): Path of the file to process.
            encoding (str): File encoding.

        Raises
            FileNotFoundError: If the file doesn’t exist.
        """
        pass
```

--------------------------------

### Remove Mentions

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/remove_fn/index

Removes mentions (strings starting with '@') from the given text using a predefined pattern.

```APIDOC
## POST /api/text/remove_mentions

### Description
Removes mentions (strings that start with '@' symbol) using the `EXPRESSION_MENTIONS` pattern.

### Method
POST

### Endpoint
/api/text/remove_mentions

### Parameters
#### Request Body
- **text** (string) - Required - The input text containing mentions.

### Request Example
```json
{
  "text": "Hello @user1, how are you @user2?"
}
```

### Response
#### Success Response (200)
- **processed_text** (string) - The text with mentions removed.

#### Response Example
```json
{
  "processed_text": "Hello , how are you ?"
}
```
```

--------------------------------

### Create TextProcessor from List of Strings

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Creates a new TextProcessor instance directly from a list of strings. This is useful when you already have your text data in a list format.

```python
lines_list = ["first line", "second line"]
processor = TextProcessor.from_list(lines_list)
```

--------------------------------

### Remove Hashtags

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/remove_fn/index

Removes hashtags (strings starting with '#') from the given text using a predefined pattern.

```APIDOC
## POST /api/text/remove_hashtags

### Description
Removes hashtags (strings that start with '#' symbol) using the `EXPRESSION_HASHTAGS` pattern.

### Method
POST

### Endpoint
/api/text/remove_hashtags

### Parameters
#### Request Body
- **text** (string) - Required - The input text containing hashtags.

### Request Example
```json
{
  "text": "This is a #sample #hashtag."
}
```

### Response
#### Success Response (200)
- **processed_text** (string) - The text with hashtags removed.

#### Response Example
```json
{
  "processed_text": "This is a  ."
}
```
```

--------------------------------

### Define English Hashtag Regex Pattern - Python

Source: https://maha.readthedocs.io/en/latest/_modules/maha/expressions/english

Defines a regular expression pattern for English hashtags. It uses imported constants for punctuation and character sets. The pattern is constructed to identify hashtags starting with '#' followed by alphanumeric characters and underscores, ensuring it's preceded by whitespace or the start of a line and not part of certain punctuation. This pattern is encapsulated within the `maha.rexy.Expression` class.

```python
from maha.constants import (
    AND_SIGN,
    AT_SIGN,
    ENGLISH_LETTERS,
    ENGLISH_NUMBERS,
    HASHTAG,
    PUNCTUATIONS,
    UNDERSCORE,
)
from maha.rexy import Expression


EXPRESSION_ENGLISH_HASHTAGS = Expression(
    r"(?<=\s|^|\n|{0})(#([{0}_]-?)+)\b".format(
        "|".join(
            [
                re.escape(pun)
                for pun in PUNCTUATIONS
                if pun not in [AT_SIGN, AND_SIGN, UNDERSCORE]
            ]
        ),
        "".join(ENGLISH_LETTERS + ENGLISH_NUMBERS),
    )
)

""" Expression that matches English hashtags """
```

--------------------------------

### Remove hashtags from text

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/remove_fn/index

This function removes hashtags (strings starting with #) from the given text using a predefined regular expression pattern for hashtags.

```python
from maha.cleaners.functions import remove_hashtags
text = "ويمكن القول أن مكة المكرمة من أجمل المناطق على وجه الأرض #السعودية"
remove_hashtags(text)
'ويمكن القول أن مكة المكرمة من أجمل المناطق على وجه الأرض'
```

--------------------------------

### BaseProcessor Class

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Documentation for the BaseProcessor class, which serves as the foundation for all other processors.

```APIDOC
## BaseProcessor Class

### Description
Base class for all processors. It contains almost all functions needed for the processors.

### Parameters
- **text** (Union[List[str], str]) - The text or list of strings to process.

### Methods

#### `get_lines(n_lines=100)`
Returns a generator of lists of strings, each with a maximum length of `n_lines`.

Parameters:
- **n_lines** (int) - Number of lines to yield. Defaults to 100.

Yields:
- List[str] - A list of strings with the specified `n_lines`. The last list may be shorter.

#### `_apply(fn)`
Applies a given function to each line of the text.

Parameters:
- **fn** (Callable[[str], str]) - The function to apply to each line.

#### `_filter(fn)`
Keeps only the lines for which the input function returns True.

Parameters:
- **fn** (Callable[[str], bool]) - The function used for filtering.

#### `get(unique_characters=False, character_length=False, word_length=False)`
Returns statistics about the provided text.

Parameters:
- **unique_characters** (bool, optional) - If True, returns all unique characters. Defaults to False.
- **character_length** (bool, optional) - If True, returns the character length of each string. Defaults to False.
- **word_length** (bool, optional) - If True, returns the word length of each string (split by space). Defaults to False.

Returns:
- Union[Dict[str, Any], Any] - If one argument is True, its corresponding value is returned. If multiple arguments are True, a dictionary with the keys of the True arguments and their values is returned.

#### `print_unique_characters()`
Prints all unique characters found in the text.

#### `keep(...)`
Applies `keep()` logic to each line based on specified character types.

Parameters:
- **arabic** (bool)
- **english** (bool)
- **arabic_letters** (bool)
- **english_letters** (bool)
- **english_small_letters** (bool)
- **english_capital_letters** (bool)
- **numbers** (bool)
- **harakat** (bool)
- **all_harakat** (bool)
- **punctuations** (bool)
- **arabic_numbers** (bool)
- **english_numbers** (bool)
- **arabic_punctuations** (bool)
- **english_punctuations** (bool)
- **use_space** (bool) - Whether to include spaces. Defaults to True.
- **custom_strings** (Union[List[str], str, None]) - Custom strings to keep.

#### `normalize(...)`
Applies normalization rules to each line.

Parameters:
- **lam_alef** (Union[bool, None])
- **alef** (Union[bool, None])
- **waw** (Union[bool, None])
- **yeh** (Union[bool, None])
- **teh_marbuta** (Union[bool, None])
- **ligatures** (Union[bool, None])
- **spaces** (Union[bool, None])
- **all** (Union[bool, None]) - Apply all normalization rules.

#### `connect_single_letter_word(...)`
Applies logic to connect single-letter words in each line.

Parameters:
- **waw** (Union[bool, None])
- **feh** (Union[bool, None])
- **beh** (Union[bool, None])
- **lam** (Union[bool, None])
- **kaf** (Union[bool, None])
- **teh** (Union[bool, None])
- **all** (Union[bool, None]) - Apply to all specified single-letter words.
- **custom_strings** (Union[List[str], str, None]) - Custom strings to consider.

#### `replace(strings, with_value)`
Applies a find and replace operation to each line.

Parameters:
- **strings** (Union[List[str], str]) - The string(s) to find.
- **with_value** (str) - The string to replace with.

#### `replace_expression(expression, with_value)`
Replaces text based on a given expression.

Parameters:
- **expression** (Union[Expression, ExpressionGroup, str]) - The expression to match.
- **with_value** (Union[Callable[..., str], str]) - The replacement value or function.

#### `replace_pairs(keys, values)`
Replaces pairs of keys with corresponding values in each line.

Parameters:
- **keys** (List[str]) - A list of strings to find.
- **values** (List[str]) - A list of strings to replace with.

#### `reduce_repeated_substring(min_repeated=3, reduce_to=2)`
Reduces repeated substrings in each line.

Parameters:
- **min_repeated** (int) - The minimum number of repetitions to trigger reduction. Defaults to 3.
- **reduce_to** (int) - The number of repetitions to reduce to. Defaults to 2.

```

--------------------------------

### Initializing relativedelta with keyword arguments

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/time/template/index

Shows how to initialize a relativedelta object using keyword arguments for absolute or relative time components. This allows for precise manipulation of datetime objects.

```python
from dateutil.relativedelta import relativedelta

relativedelta(year=Y, month=M, day=D, hour=H, minute=MI, second=S, microsecond=MS,
              years=y, months=m, days=d, weeks=w, hours=h, minutes=mi, seconds=s, microseconds=ms,
              weekday=WD, leapdays=LD, yearday=YD, nlyearday=NLYD, am_pm=AP, hijri=HI)
```

--------------------------------

### Run All Project Tests with Poetry and Tox (Python)

Source: https://maha.readthedocs.io/en/latest/contributing/guidelines

Executes all defined project tests and checks using Poetry and Tox. This command ensures that code style, integration tests, and doctests pass across different Python versions and operating systems.

```shell
poetry run tox

```

--------------------------------

### Important Directive Example

Source: https://maha.readthedocs.io/en/latest/contributing/admonitions

Shows the 'important' directive, used to highlight crucial information that requires user attention. Content within the directive is emphasized.

```rst
.. important::
   Some important information which should be considered.

```

--------------------------------

### Initialize StreamTextProcessor

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Initializes a StreamTextProcessor for processing an iterable of strings, suitable for large or streaming data.

```python
data_stream = iter(["line A", "line B", "line C"])
stream_processor = StreamTextProcessor(data_stream)
```

--------------------------------

### ObjectGet Class

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/utils/index

Details the ObjectGet class, its attributes, and its usage within the BaseProcessor.

```APIDOC
## ObjectGet Class

### Description
Used with the `get` function in `BaseProcessor`.

### Method
N/A (Class Definition)

### Endpoint
N/A (Class Definition)

### Parameters
N/A (Class Definition)

### Request Example
N/A (Class Definition)

### Response
N/A (Class Definition)

## ObjectGet Attributes

### Description
Attributes of the ObjectGet class.

### Method
N/A (Attribute Access)

### Endpoint
N/A (Attribute Access)

### Parameters

#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## ObjectGet.func

### Description
Represents a callable function associated with ObjectGet.

### Method
N/A (Attribute)

### Endpoint
N/A (Attribute)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **type**: `Callable` - The callable function.

#### Response Example
N/A

## ObjectGet.prev

### Description
Represents the previous value or state associated with ObjectGet.

### Method
N/A (Attribute)

### Endpoint
N/A (Attribute)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **type**: `Any` - The previous value.

#### Response Example
N/A

## ObjectGet.name

### Description
Represents the name associated with ObjectGet.

### Method
N/A (Attribute)

### Endpoint
N/A (Attribute)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **type**: `str` - The name string.

#### Response Example
N/A

## ObjectGet.post_fn

### Description
Represents a post-processing callable function for ObjectGet.

### Method
N/A (Attribute)

### Endpoint
N/A (Attribute)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **type**: `Callable` - The post-processing callable function.

#### Response Example
N/A
```

--------------------------------

### FileProcessor Class

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/basic_processors/index

The FileProcessor class extends TextProcessor for handling file input. It initializes with a file path and includes error handling for non-existent or empty files.

```APIDOC
## FileProcessor Class

### Description
For processing file input.

**Note:** For large files ( > 100 MB), consider using `StreamFileProcessor`.

### Methods

#### `__init__(path)`

Initializes the FileProcessor with the path to a file.

**Parameters**

*   **path** (Union[str, pathlib.Path]) - The path of the file to process.

**Raises**

*   FileNotFoundError - If the specified file does not exist.
*   ValueError - If the specified file is empty.

```

--------------------------------

### Check for Mentions in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function checks for any mentions (starting with @) in the text, regardless of language. Use 'mentions=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "Mentioning @user1 and @مستخدم2"
result = contains(text, mentions=True)
print(result)  # Output: True
```

--------------------------------

### Create TextProcessor from Text String

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Creates a new TextProcessor instance from a given text string. The text can be separated into lines using an optional separator.

```python
processor = TextProcessor.from_text("line1\nline2\nline3")
# Or with a separator
processor_with_sep = TextProcessor.from_text("line1,line2,line3", sep=",")
```

--------------------------------

### Check for Hashtags in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function checks for any hashtags (starting with #) in the text, regardless of language. Use 'hashtags=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "A mix of #English and #عربي hashtags"
result = contains(text, hashtags=True)
print(result)  # Output: True
```

--------------------------------

### Maha Parsers Rules - Subpackages

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/index

Lists the available subpackages within maha.parsers.rules and their respective modules.

```APIDOC
## Subpackages

### `maha.parsers.rules.distance`

* `maha.parsers.rules.distance.rule`
* `maha.parsers.rules.distance.template`
* `maha.parsers.rules.distance.utils`
* `maha.parsers.rules.distance.values`

---

### `maha.parsers.rules.duration`

* `maha.parsers.rules.duration.rule`
* `maha.parsers.rules.duration.template`
* `maha.parsers.rules.duration.utils`
* `maha.parsers.rules.duration.values`

---

### `maha.parsers.rules.numeral`

* `maha.parsers.rules.numeral.rule`
* `maha.parsers.rules.numeral.values`

---

### `maha.parsers.rules.ordinal`

* `maha.parsers.rules.ordinal.rule`
* `maha.parsers.rules.ordinal.values`

---

### `maha.parsers.rules.time`

* `maha.parsers.rules.time.constants`
* `maha.parsers.rules.time.rule`
* `maha.parsers.rules.time.template`
* `maha.parsers.rules.time.values`

---
```

--------------------------------

### Maha Constants API

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/names/index

Documentation for the constants module in Maha, including submodules for Arabic, English, and Persian constants.

```APIDOC
## `maha.constants`

### Description
This module provides various constant definitions used throughout the Maha project.

### Module Contents

- `arabic`
  - `compound`
  - `simple`
- `english`
  - `compound`
  - `simple`
- `persian`
  - `compound`
  - `simple`
- `general`

### Request Example
```json
{
  "example": "No specific request body defined for this module, typically used internally."
}
```

### Response Example
```json
{
  "example": "No specific response body defined for this module, typically used internally."
}
```
```

--------------------------------

### English Constants

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/constants/english/compound/index

Retrieve lists of English characters, numbers, and punctuation.

```APIDOC
## GET /constants/english/small-letters

### Description
Retrieves a list of all small English letters.

### Method
GET

### Endpoint
/constants/english/small-letters

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **letters** (list[str]) - A list of all small English letters.

#### Response Example
```json
{
  "letters": ["a", "b", "c", ...]
}
```

## GET /constants/english/capital-letters

### Description
Retrieves a list of all capital English letters.

### Method
GET

### Endpoint
/constants/english/capital-letters

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **letters** (list[str]) - A list of all capital English letters.

#### Response Example
```json
{
  "letters": ["A", "B", "C", ...]
}
```

## GET /constants/english/all-letters

### Description
Retrieves a list of all English letters (both small and capital).

### Method
GET

### Endpoint
/constants/english/all-letters

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **letters** (list[str]) - A list of all English letters.

#### Response Example
```json
{
  "letters": ["a", "b", ..., "A", "B", ...]
}
```

## GET /constants/english/numbers

### Description
Retrieves a list of Western Arabic numerals.

### Method
GET

### Endpoint
/constants/english/numbers

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **numbers** (list[str]) - A list of Arabic numerals.

#### Response Example
```json
{
  "numbers": ["0", "1", "2", ...]
}
```

## GET /constants/english/punctuations

### Description
Retrieves a list of English punctuation marks.

### Method
GET

### Endpoint
/constants/english/punctuations

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **punctuations** (list[str]) - A list of English punctuation marks.

#### Response Example
```json
{
  "punctuations": [".", ",", "!", "?", ...]
}
```

## GET /constants/english/common

### Description
Retrieves a list of common English characters.

### Method
GET

### Endpoint
/constants/english/common

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **characters** (list[str]) - A list of common English characters.

#### Response Example
```json
{
  "characters": ["a", "b", "c", "1", "2", "3", ".", ",", ...]
}
```
```

--------------------------------

### Define Day Enum in Python

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/templates/enums

The Day enumeration defines the days of the week. It assigns auto-generated values to Monday through Sunday, starting with Monday explicitly set to 0.

```python
[docs]class Day(Enum):

[docs]    MONDAY = 0


[docs]    TUESDAY = auto()


[docs]    WEDNESDAY = auto()


[docs]    THURSDAY = auto()


[docs]    FRIDAY = auto()


[docs]    SATURDAY = auto()


[docs]    SUNDAY = auto()
```

--------------------------------

### Initialize Regex Expression from Cache (Python)

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/names

This code snippet demonstrates how to initialize a regular expression expression from a cache using the `Expression.from_cache` method. It imports the necessary `Expression` class from the `maha.rexy` module and defines a constant `RULE_NAME` by calling the caching method with a specific rule name ('names').

```Python
from maha.rexy import Expression


[docs]RULE_NAME = Expression.from_cache("names")
```

--------------------------------

### Reduce repeated substrings using Maha

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/remove_fn/index

This function reduces consecutive substrings that are repeated a minimum number of times to a specified number of times. For example, 'hhhhhh' can be reduced to 'hh' with default settings.

```python
from maha.cleaners.functions import reduce_repeated_substring
text = "ههههههههههههههه"
reduce_repeated_substring(text)
'هه'
```

```python
from maha.cleaners.functions import reduce_repeated_substring
text = "ويييييييييين راححححححححححححوا"
reduce_repeated_substring(text, reduce_to=1)
'وين راحوا'
```

--------------------------------

### Specific Processor Classes

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Documentation for specialized processor classes that inherit from BaseProcessor.

```APIDOC
## Specific Processor Classes

### Description
These classes extend the `BaseProcessor` to handle specific types of input or processing needs.

### Classes

- `TextProcessor`: For processing text input.
- `FileProcessor`: For processing file input.
- `StreamTextProcessor`: For processing a stream of text input.
- `StreamFileProcessor`: For processing a file stream input.

_Note: Detailed method documentation for these classes would typically be found in their respective class definitions, inheriting functionality from `BaseProcessor`._

```

--------------------------------

### Check for English Mentions in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function identifies English mentions (starting with @ followed by English characters) in the text. Set 'english_mentions=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "Thanks @username"
result = contains(text, english_mentions=True)
print(result)  # Output: True
```

--------------------------------

### Check for English Hashtags in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function checks for English hashtags (starting with # followed by English characters) in the text. Use 'english_hashtags=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "This is #MyHashtag"
result = contains(text, english_hashtags=True)
print(result)  # Output: True
```

--------------------------------

### Check for Arabic Mentions in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function identifies Arabic mentions (starting with @ followed by Arabic characters) in the text. Set 'arabic_mentions=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "شكرا لك @مستخدم_عربي"
result = contains(text, arabic_mentions=True)
print(result)  # Output: True
```

--------------------------------

### Check for Arabic Hashtags in Text using Python

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

This function checks for Arabic hashtags (starting with # followed by Arabic characters) in the text. Use 'arabic_hashtags=True'. Returns a boolean.

```python
from py_stringmatching.similarity_measure.contains import contains

text = "هذا #وسم_عربي"
result = contains(text, arabic_hashtags=True)
print(result)  # Output: True
```

--------------------------------

### Maha Parsers Rules - Submodules

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/index

Lists the available submodules within the maha.parsers.rules package.

```APIDOC
## Submodules

* `maha.parsers.rules.common`
* `maha.parsers.rules.names`

---
```

--------------------------------

### Get Lines from Stream/File Processor

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Retrieves a generator yielding lists of strings, with each list having a specified maximum length. The last list may be shorter than the specified length. This method is available in StreamTextProcessor and StreamFileProcessor.

```python
class StreamTextProcessor:
    def get_lines(self, n_lines=100):
        """
        Returns a generator of list of strings with length of `n_lines`

        Parameters
            n_lines (int): Number of lines to yield, Defaults to 100

        Yields
            List[str]: List of strings with length of `n_lines`. The last list maybe of length less than `n_lines`.
        """
        pass

class StreamFileProcessor(StreamTextProcessor):
    def get_lines(self, n_lines=100):
        """
        Returns a generator of list of strings with length of `n_lines`

        Parameters
            n_lines (int): Number of lines to yield, Defaults to 100

        Yields
            List[str]: List of strings with length of `n_lines`. The last list maybe of length less than `n_lines`.
        """
        pass
```

--------------------------------

### Define Before and After Fraction Patterns (Python)

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/numeral/rule

Creates expression groups for fractions that can appear before or after a numeral, such as 'half', 'third', 'quarter', and their counterparts. These are essential components for parsing complex fractional expressions. Dependencies include ExpressionGroup.

```python
BEFORE_FRACTIONS = ExpressionGroup(HALF, THIRD, QUARTER)
AFTER_FRACTION = ExpressionGroup(THREE_QUARTERS, TWO_THIRDS, MULTIPLIERS_FRACTION)
before_fractions_group = named_group("before_fractions", BEFORE_FRACTIONS.join())
after_fraction_group = named_group("after_fraction", AFTER_FRACTION.join())
```

--------------------------------

### Initializing relativedelta with two datetimes

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/time/template/index

Demonstrates initializing a relativedelta object by providing two datetime objects. This method is used to calculate the difference between two points in time.

```python
from dateutil.relativedelta import relativedelta

relativedelta(datetime1, datetime2)
```

--------------------------------

### Define Arabic 'Before' Expression

Source: https://maha.readthedocs.io/en/latest/_modules/maha/parsers/rules/common

Defines a regular expression pattern for the Arabic word 'قبل' (before), allowing for optional prefixes like 'إلى' or 'اللي' followed by a space. This helps in identifying preceding events or items.

```python
BEFORE = Expression(
    optional_non_capturing_group("[إا]لل?ي" + EXPRESSION_SPACE) + "[أاق]بل"
)

```

--------------------------------

### Maha Parsers Templates API

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/parsers/rules/names/index

Documentation for the templates module within maha.parsers, detailing submodules like dimension, enums, text_expression, and value_expressions.

```APIDOC
## `maha.parsers.templates`

### Description
This module contains various template structures for parsing operations.

### Module Contents

- `dimension`
- `enums`
- `text_expression`
- `value_expressions`

### Request Example
```json
{
  "example": "No specific request body defined for this module, typically used internally."
}
```

### Response Example
```json
{
  "example": "No specific response body defined for this module, typically used internally."
}
```
```

--------------------------------

### Remove Punctuation from Arabic Text

Source: https://maha.readthedocs.io/en/latest/overview

The `remove` function in `maha.cleaners.functions` is used to strip specific characters from a given text. This example shows how to remove all punctuation marks. It accepts the input text and a boolean flag to indicate punctuation removal.

```python
>>> from maha.cleaners.functions import remove
>>> sample_text = "البسملة : ( بِسْمِ اللَّـهِ الرَّحْمَـٰنِ الرَّحِيمِ )"
>>> remove(sample_text, punctuations=True)
'البسملة بِسْمِ اللَّـهِ الرَّحْمَـٰنِ الرَّحِيمِ'
```

```python
>>> from maha.cleaners.functions import remove
>>> sample_text = "#بسم_الله_الرحمن_الرحيم"
>>> remove(sample_text, punctuations=True)
'بسم الله الرحمن الرحيم'
```

--------------------------------

### Process and Save File Content

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/processors/index

Processes the content of an input file and saves the processed result to a specified output path. Allows overriding the output file if it already exists. Parameters include the output path, lines per process chunk, and an override flag. Raises FileExistsError if override is False and the file exists.

```python
class StreamFileProcessor:
    def process_and_save(self, path, n_lines=100, override=False):
        """
        Process the input file and save the result in the given path

        Parameters
            path (Union[str, pathlib.Path]): Path to save the file
            n_lines (int, optional): Number of lines to process at a time, by default 100
            override (bool, optional): True to override the file if exists, by default False

        Raises
            FileExistsError: If the file exists
        """
        pass
```

--------------------------------

### Remove Hashtags from Text

Source: https://maha.readthedocs.io/en/latest/autoapi/maha/cleaners/functions/index

Removes hashtags (strings starting with '#') from the given text using the `EXPRESSION_HASHTAGS` pattern. It processes a string and returns the text without any hashtags. Ideal for cleaning social media text.

```python
from maha.cleaners.functions import remove_hashtags
>>> text = "ويمكن القول أن مكة المكرمة من أجمل المناطق على وجه الأرض #السعودية"
>>> remove_hashtags(text)
'ويمكن القول أن مكة المكرمة من أجمل المناطق على وجه الأرض'
```

--------------------------------

### Check for Arabic Letters in Text

Source: https://maha.readthedocs.io/en/latest/overview

The `contains` function from `maha.cleaners.functions` checks if a given text includes specific types of characters. This example verifies the presence of Arabic letters. It returns a boolean value indicating whether Arabic letters were found.

```python
>>> from maha.cleaners.functions import contains
>>> sample_text = "أنا وأخي علي في المكتبةِ نَدرسُ البرمجه"
>>> contains(sample_text, arabic_letters=True)
True
```

--------------------------------

### Extract Emails using Maha Parser

Source: https://maha.readthedocs.io/en/latest/overview

Demonstrates how to extract email addresses from a text using the `parse` function with the `emails=True` parameter. The output lists each extracted email with its position in the original text.

```python
from maha.parsers.functions import parse
sample_text = "الإيميل: test@example.com أو test2@example.com"
parse(sample_text, emails=True)
[Dimension(body=test@example.com, value=test@example.com, start=9, end=25, dimension_type=DimensionType.EMAILS), Dimension(body=test2@example.com, value=test2@example.com, start=29, end=46, dimension_type=DimensionType.EMAILS)]
```