struct-package 1.0.0
A package for defining structure like C++ language!
Requires Python: >=3.6

# **Structure**: A package for defining structure like C++ language!

`Structure` allows you to create simple and efficient data structures that resemble C++ structs, combining the power of Python's dynamic typing and type annotations. By inheriting from the `Structure` class, you can define structured objects with attributes, where type safety is enforced at runtime.

## **Features**

- **Type-based attribute validation**: Ensures that only valid attributes are set based on type annotations, providing built-in validation for data integrity.
- **Inheritance**: You can extend `Structure` to create custom structs, making it easier to define complex data types.
- **Error handling**: Provides automatic validation for attribute names and types. If an invalid attribute or type is encountered, a `ValueError` will be raised.
- **Dynamic data assignment**: Supports dynamic assignment of attributes during instantiation, making it easy to initialize your structs with different data.

## **Installation**

To install `Structure`, use pip:

```bash
pip install Structure
```

## **Usage**

### 1. **Creating a Struct**

To create a struct, simply inherit from the `Struct` class and define the attributes with Python type annotations.

```python
from pystruct import Struct

class Person(Struct):
    name: str
    age: int

# Instantiate the struct
person = Person(name='John Doe', age=30)
print(person.name)  # Output: John Doe
print(person.age)   # Output: 30
```

### 2. **Attribute Validation**

The package will ensure that only attributes declared in the class's annotations are assigned. Any additional attributes will raise a `ValueError`.

```python
try:
    person = Person(name='Alice', age=25, address='123 Main St')
except ValueError as e:
    print(e)  # Output: Invalid attribute 'address' for Person
```

### 3. **Type Validation**

Attributes are validated based on their type annotations. If you try to assign a value of the wrong type, a `ValueError` will be raised.

```python
try:
    person = Person(name='Bob', age='thirty')
except ValueError as e:
    print(e)  # Output: Invalid type for 'age', expected <class 'int'>, got <class 'str'>
```

### 4. **Custom Structs**

You can inherit from `Struct` to create your own data structures with specific attributes and types:

```python
class Car(Struct):
    make: str
    model: str
    year: int

car = Car(make='Tesla', model='Model S', year=2022)
print(car.make)  # Output: Tesla
```

### 5. **Accessing and Modifying Attributes**

You can access and modify the attributes just like any normal class, but any invalid attribute assignments will raise errors:

```python
car.year = 2023
print(car.year)  # Output: 2023

# Attempting to assign an invalid attribute
try:
    car.color = 'Red'
except ValueError as e:
    print(e)  # Output: Invalid attribute 'color' for Car
```

### 6. **Inheritance and Extending Structs**

You can further extend structs by creating new classes that inherit from an existing struct, making it easy to build upon and extend the functionality:

```python
class ElectricCar(Car):
    battery_size: int

electric_car = ElectricCar(make='Tesla', model='Model 3', year=2023, battery_size=75)
print(electric_car.battery_size)  # Output: 75
```

## **Error Handling**

- **Invalid Attributes**: If you attempt to assign an attribute that isn't defined in the class's type annotations, a `ValueError` is raised.
- **Invalid Types**: If the value assigned to an attribute doesn't match the type annotation, a `ValueError` is raised indicating the expected type and the actual type provided.

## **Advanced Features**

- **Default Values**: You can provide default values for attributes if needed, for example, by using `None` for optional fields.
- **Custom Validation**: You can also extend the class and implement custom validation methods for more complex structures.

---

## **Contributing**

If you'd like to contribute to the `Structure` package, feel free to fork the repository and submit a pull request with your improvements.