transform-utils 1.0.0
this package for utils

# Transform Class

The `Transform` class is a Python utility for performing data transformations on structured data.
It provides a set of methods to manipulate, aggregate, and derive new data based on the given input.
The class is designed to be flexible and extensible, allowing users to chain multiple transformation operations.

## Table of Contents

1. [Installation](#installation)
2. [Usage](#usage)
    - [Initialization](#initialization)
    - [Data Parsing](#data-parsing)
    - [Transformation Operations](#transformation-operations)
3. [Examples](#examples)
4. [Methods](#methods)
    - [Common Methods](#common-methods)
    - [Transformation Methods](#transformation-methods)
5. [Contributing](#contributing)
6. [License](#license)

## Installation

```bash
pip install transform-utils
```

## Usage

### Initialization

```python
from transform import Transform

# Initialize Transform instance
transformer = Transform(path='root', separator='.', field1, field2, ...)
```

### Data Parsing

```python
# Parse JSON payload
transformer.parse(json_payload)

# Access transformed data
result = transformer.result
```

### Transformation Operations

```python
# Perform transformations
transformer.transform(field1, field2, ...).sort('column_name').to_json()
```

## Examples

```python
# Example 1: Parsing and Transforming Data
transformer = Transform(path='data', separator='.', 'name', 'age', 'city')
result = transformer.parse(json_data).transform('name', 'age').to_json()

# Example 2: Aggregation and Sorting
transformer = Transform(path='records', separator='.', 'category', 'value')
result = transformer.sum('category', 'value', alias='total').sort('-total').to_json()
```

## Methods

### Common Methods

- `__init__(self, path='root', separator='.', *args)`: Initialize the Transform instance.
    - Parameters:
    - `path`: Root path in the input data (default is 'root').
    - `separator`: Separator used in field paths (default is '.').
    - `args`: List of field names to be selected for transformation.

- `parse(self, payload) -> Transform`: Parse and set the input data for transformation.
    - Parameters:
    - `payload`: JSON data or string to be parsed.
    - Returns:
    - `Transform`: Instance of the Transform class.

- `to_json(self, indent=2) -> str`: Convert the transformed data to JSON format.
    - Parameters:
    - `indent`: Number of spaces to use for indentation (default is 2).
    - Returns:
    - `str`: JSON-formatted string.

### Transformation Methods

- `transform(self, *fields) -> Transform`: Apply transformations to selected fields.
    - Parameters:
    - `fields`: List of field names to be transformed.
    - Returns:
    - `Transform`: Instance of the Transform class.

- `count(self, group_by, alias='', sort='') -> Transform`: Count occurrences based on a grouping field.
    - Parameters:
    - `group_by`: Field for grouping.
    - `alias`: Alias for the count column (default is '').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `average(self, group_by, field, alias='', sort='') -> Transform`: Calculate the average value based on a grouping field.
    - Parameters:
    - `group_by`: Field for grouping.
    - `field`: Field for calculating the average.
    - `alias`: Alias for the result column (default is '').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `sum(self, group_by, field, alias='', sort='') -> Transform`: Sum values based on a grouping field.
    - Parameters:
    - `group_by`: Field for grouping.
    - `field`: Field for summing.
    - `alias`: Alias for the sum column (default is '').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `max(self, group_by, field, alias='', sort='') -> Transform`: Find the maximum value based on a grouping field.
    - Parameters:
    - `group_by`: Field for grouping.
    - `field`: Field for finding the maximum.
    - `alias`: Alias for the result column (default is '').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `min(self, group_by, field, alias='', sort='') -> Transform`: Find the minimum value based on a grouping field.
    - Parameters:
    - `group_by`: Field for grouping.
    - `field`: Field for finding the minimum.
    - `alias`: Alias for the result column (default is '').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `mod(self, field, by=0, name='mod', sort='') -> Transform`: Apply modulo operation on a field.
    - Parameters:
    - `field`: Field for applying the modulo operation.
    - `by`: Divisor for modulo operation (default is 0).
    - `name`: Name for the result column (default is 'mod').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `pow(self, field, by=0, name='pow', sort='') -> Transform`: Apply power operation on a field.
    - Parameters:
    - `field`: Field for applying the power operation.
    - `by`: Exponent for power operation (default is 0).
    - `name`: Name for the result column (default is 'pow').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `ceil(self, field, name='ceil', sort='') -> Transform`: Apply ceil operation on a numeric field.
    - Parameters:
    - `field`: Numeric field for applying the ceil operation.
    - `name`: Name for the result column (default is 'ceil').
    - `sort`: Field to sort by (default is '').
    - Returns:
    - `Transform`: Instance of the Transform class.

- `floor(self, field, name='floor', sort='') -> Transform`: Apply floor operation on a numeric field.
    - Parameters:
    - `field`: Numeric field for applying the floor operation.
    - `name`: Name for the result column (default is 'floor').

## Contributing

If you'd like to contribute to this project, please follow the [contribution guidelines](CONTRIBUTING.md).

## License

This project is licensed under the [MIT License](LICENSE).