# PrasBridge
## About
**PrasBridge is a powerful Python package that seamlessly integrates Django and SQLAlchemy, providing enhanced form handling, serialization capabilities, and utility functions for building robust web applications.**
[](https://badge.fury.io/py/PrasBridge)
[](https://pypi.org/project/PrasBridge/)
[](https://pypi.org/project/PrasBridge/)
## Features
- 🔄 Seamless Django and SQLAlchemy Integration
- 📝 Enhanced Form Fields with Extra Functionality
- 🔐 Built-in Authentication Forms
- 🎨 Customizable Form Rendering
- 📦 Flexible Model Serialization
- 🛠️ Utility Functions (Token Generation, Slugify)
- 💼 Session Management
- 🏷️ Custom Template Tags
## Installation
```bash
pip install PrasBridge
```
## Quick Start
### 1. Configure Database Connection
```python
# settings.py
DATABASES = {
'sqlalchemy': {
'URL': 'your-database-url-here'
}
}
```
### 2. Config Installed App
```python
# settings.py
INSTALLED_APPS = [
...
'pras',
]
```
### 3. Create Models
```python
# models.py
from pras.models import PrasBase, BaseUser
class User(BaseUser):
__tablename__ = 'users'
# Additional fields can be added here
...
```
### 4. Form Handling
```python
from pras.forms import CharField, EmailField, RegistrationForm
class CustomRegistrationForm(RegistrationForm):
bio = CharField(max_length=500, required=False)
website = CharField(max_length=200, required=False)
def __init__(self, *args, **kwargs):
super().__init__(model=User, *args, **kwargs)
```
### 5. Template Tags
```django
{% load pras %}
<form method="post">
{% csrf_token %}
{% pInput "username" form=form label=True error=True %}
{% pInput "email" form=form InputClass="custom-input" %}
{% pInput "password" form=form type="password" %}
<button type="submit">Submit</button>
</form>
```
## Detailed Features
---
### Base Models
**PrasBridge provides robust base models designed to streamline essential fields for various classes, supporting extensibility and ease of use in applications.**
#### `PrasBase`
`PrasBase` is a foundational model for any entity that requires automatic tracking of creation and modification timestamps. It includes the following fields:
- `id:` Auto-generated primary key for unique identification of each instance.
- `created_at:` Automatically stores the date and time the instance was created.
- `updated_at:` Tracks the date and time of the most recent update to the instance.
#### `BaseUser`
`BaseUser` builds on PrasBase and provides a structured template for user models. It includes essential fields for managing user accounts and permissions:
- `username:` Unique identifier for each user.
- `first_name:` User’s first name.
- `last_name:` User’s last name.
- `email:` User’s email address, typically also unique.
- `password:` Stores the user’s hashed password.
- `is_active:` Boolean indicating if the account is active.
- `is_staff:` Boolean flag for administrative permissions.
- `is_superuser:` Boolean flag for superuser permissions.
- `date_joined:` Timestamp indicating when the user account was created.
- `PrasBase:` Inherits `id`, `created_at`, and `updated_at` fields from `PrasBase`.
These fields make `BaseUser` an ideal base for user authentication and authorization in applications, with built-in fields for permissions and user management.
##### Example
```python
from pras import PrasBase, BaseUser
# Custom user model inheriting from BaseUser for applications that require user profiles
class User(BaseUser):
__tablename__ = 'users'
# Additional fields and methods specific to User can be added here
...
# Example model for a library system
class Book(PrasBase):
__tablename__ = 'books'
title = Column(String, nullable=False)
author = Column(String, nullable=False)
isbn = Column(String, unique=True, nullable=False)
...
# Additional attributes and methods specific to Book can be defined here
```
##### Notes
- `Flexibility:` Both `PrasBase` and `BaseUser` provide a flexible base structure that you can extend to suit specific application needs.
- `Consistency:` Utilizing these models ensures that essential fields like `created_at` and `updated_at` are consistently applied across your application.
- `Customizability:` By inheriting from these bases, additional fields can be seamlessly added to create tailored entities.
---
### Enhanced Form Fields
**PrasBridge provides a suite of enhanced form fields with customizable options for common field types, including:**
- `CharField`
- `EmailField`
- `TextAreaField`
- `ChoiceField`
- `CheckboxField`
- `DateField`
- `IntegerField`
---
#### Common Arguments
**These arguments apply to all PrasBridge form fields, providing flexible customization for events, accessibility, and styling:**
- **Events:** `onclick`, `onfocus`, `onblur`, `onchange` – JavaScript functions for handling user interactions.
- **Attributes:** `required`, `disabled`, `readonly`, `autocomplete` – Common HTML attributes for form fields.
- **Styling and Classes:** `classes`, `style`, `id` – Options to add CSS classes, inline styles, and set a unique ID.
- **Display Options:** `label`, `label_suffix`, `help_text` – Control label visibility, label suffix, and help text for field hints.
- **Field-Specific Options:** `initial`, `value`, `show_hidden_initial`, `localize`, `validators`, `data_attrs`, `aria_attrs` – Set initial values, localize content, and add custom validation and data attributes.
---
#### Field Types
Each field type in PrasBridge includes arguments that are commonly defined using Django's attrs dictionary for widgets. PrasBridge fields offer these as direct arguments for ease of use.
---
##### CharField and EmailField
**`CharField` and `EmailField` allow direct assignment of common attributes without defining them within `attrs={}`.**
- **Arguments**
- `type (CharField only):` Field type, such as "text", "email", or "password".
- `placeholder:` Placeholder text within the field.
- `max_length / min_length:` Constraints on the length of input.
- `title:` Tooltip text.
- `size:` Size of the input field.
- `strip:` Strips whitespace if True.
- `empty_value:` Value if the field is empty.
- **Note**
- `type` argument is only for CharField
- `CharField` can be set to `email` type, `EmailField` offers enhanced validation and error handling for email input.
- **Example**
```python
from pras.forms.fields import CharField, EmailField
class MyForm(forms.Form):
name = CharField(
type="text", # text, email, or password
placeholder="Enter your name",
required=True,
...
)
email = EmailField(
placeholder="Enter your email",
...
)
```
---
##### TextAreaField
**PRAS’s `TextAreaField` streamlines attribute customization, bypassing the need for `attrs={}`.**
- **Arguments**
- `rows / cols:` Set the dimensions of the text area.
- `placeholder:` Placeholder text for the field.
- `max_length / min_length:` Limits on text length.
- `size:` Size of the field.
- `strip:` Strips whitespace if True.
- `empty_value:` Value if the field is empty.
- **Example**
```python
from pras.forms.fields import TextAreaField
class MyForm(forms.Form):
bio = TextAreaField(
rows=4,
cols=50
...
)
```
---
##### ChoiceField
**ChoiceField supports predefined options without needing a widget definition.**
- **Arguments**
- `choices:` List of tuple pairs representing value-label options.
- **Example**
```python
from pras.forms.fields import ChoiceField
class MyForm(forms.Form):
gender = ChoiceField(
choices=[('Male', 'Male'), ('Female', 'Female')],
...
)
```
---
##### CheckboxField
**PRAS’s CheckboxField allows easy configuration of checked status.**
- **Arguments**
- `checked:` Boolean, if True, checkbox appears selected.
- **Example**
```python
from pras.forms.fields import CheckboxField
class MyForm(forms.Form):
agree = CheckboxField(
checked=True,
...
)
```
---
##### DateField
**DateField supports date input with optional format validation.**
- **Arguments**
- `input_formats:` List of accepted date formats for validation.
- **Example**
```python
from pras.forms.fields import DateField
class MyForm(forms.Form):
birthdate = DateField(
input_formats=["%Y-%m-%d"],
...
)
```
##### IntegerField
**IntegerField provides constraints and step control for numeric inputs.**
- **Arguments**
- `min_value / max_value:` Limits for accepted values.
- `step:` Increment step size
- **Example**
```python
from pras.forms.fields import IntegerField
class MyForm(forms.Form):
age = IntegerField(
min_value=18,
max_value=100,
step=1,
...
)
```
### Built-in Forms
**PrasBridge Provides built-in forms for common authentication and registration.**
- **AuthenticationForm**
- **RegistrationForm**
These forms handle the save functionality after cleaning and validating user input. However, both forms require a valid user model to function correctly—without one, they will raise an error. To use these forms, pass a valid model upon creation. If you need to modify the save functionality, you can override the save method.
---
#### Example
```python
# forms.py
from pras.forms import AuthenticationForm, RegistrationForm
from pras.forms.fields import CharField
from .models import User
# Extending the AuthenticationForm
class MyAuthenticationForm(AuthenticationForm):
confirm_password = CharField(
type="password",
placeholder="Confirm password",
required=True
)
def __init__(self, *args, **kwargs):
# Pass a valid user model for `save` functionality
super().__init__(model=User, *args, **kwargs)
# views.py
from .forms import MyAuthenticationForm
from .models import User
from pras.forms import AuthenticationForm
def login(request):
# Custom form instance with a specified model
form = MyAuthenticationForm(
model=User, # Optional if the model is set in the form class
data=request.POST or None
)
# Alternatively, use the main AuthenticationForm without extending it
form = AuthenticationForm(model=User, data=request.POST or None)
if form.is_valid():
form.save() # Completes the login process with a valid User model
return render(request, 'login.html', {'form': form})
# Same for RegistrationForm also you need to pass a valid user model for `save` functionality like above
```
#### Note
- **The same usage applies for `RegistrationForm` as it does for `AuthenticationForm`:** Both forms require a valid user model to utilize the save functionality, whether you’re using them directly or extending them.
- **Best Practice for Extending Forms:** When extending `AuthenticationForm`, `RegistrationForm`, or any other form within PRAS, it’s recommended to use the form fields provided by PrasBridge (`CharField`, `EmailField`, etc.) rather than Django’s built-in fields. These PrasBridge fields offer enhanced functionality with common arguments that streamline the configuration of attributes, keeping the implementation consistent with the PrasBridge other features. Additionally, PrasBridge’s fields are essential for compatibility with other PrasBridge-specific features, such as custom tags, ensuring seamless integration and 100% compatibility across all functionalities.
---
### Serialization
**PrasBridge provides flexible serialization options for your models:**
#### Key Concepts
- **Serialization Prefix**: Use a specific prefix when defining serialization schemas. For example, use `PRAS_` as the prefix for your schemas, such as `PRAS_BasicInfo`.
- **Identifier Field**: The identifier field is crucial for defining serialization schemas. This unique field allows you to access the serialized data from the model using the `to_dict` method. You must pass the identifier to `to_dict` to serialize the data according to the specified schema.
- **Fields**: The `fields` attribute is used to define which fields to serialize. It accepts three types of patterns:
- `__all__`: Includes all fields. (default).
- `username`: Serializes and returns only the `username` field data.
- `!field_name`: Excludes the specified field from serialization. For example, use `!password` to exclude the password field.
##### Example
```python
from pras.models import BaseUser
class User(BaseUser):
__tablename__ = 'users'
# Define fields for the model
# Define serialization schemas
class PRAS_AllInfo:
__identifier__ = 'allinfo'
fields = ['__all__'] # Returns all data of the model
class PRAS_UsernameInfo:
__identifier__ = 'specific'
fields = ['username'] # Returns only the username field data
class PRAS_ExcludeInfo:
__identifier__ = 'exclude'
fields = ['!password'] # Returns all data except the password field
# Usage
user = User.query.first()
all_info = user.to_dict('allinfo') # All user data
username_info = user.to_dict('specific') # Only username data
exclude_info = user.to_dict('exclude') # All data except password
```
- **Serializing Related Models**: To serialize related models, define a serialization pattern for related fields. For instance, if a model has a field `user = relationship(User)`, you need to specify the fields you wish to include.
- **Supported Patterns**:
- `__all__`: Include all fields of the related model.
- `!field_name`: Exclude specified fields.
- `field_name`: Include only that specific field.
##### Example
```python
from pras.models import PrasBase, BaseUser
class User(BaseUser):
__tablename__ = 'users'
# Define fields for the user model
...
class Book(PrasBase):
__tablename__ = 'books'
user_id = Column(Integer, ForeignKey('users.id'))
user = relationship(User)
...
# Define serialization schema
class PRAS_BookInfo:
__identifier__ = 'bookinfo'
user = ['username', 'email'] # Returns only username and email of the related user named field
fields = ['__all__'] # Returns all data of the Book model
# Usage
book = Book.query.first()
book_info = book.to_dict('bookinfo') # Serializes book data along with specified user fields
```
##### Serializing Without `PrasBase` or `BaseUser`
While `PrasBase` and `BaseUser` are designed for seamless integration with PrasBridge serialization features with SQLAlchemy, you can enable serialization for models that don’t use them by implementing the following:
```python
from pras.serializers import PrasSerializer, IntegratedMeta # Import PrasSerializer and IntegratedMeta
from sqlalchemy.ext.declarative import declarative_base # Import SQLAlchemy's declarative base
Base = declarative_base(metaclass=IntegratedMeta) # Pass IntegratedMeta to sync PrasBridge serialization
class MyModel(Base, PrasSerializer): # Inherit Base and PrasSerializer
__tablename__ = 'users'
...
class PRAS_BookInfo:
__identifier__ = 'bookinfo'
fields = ['__all__']
```
##### Note
- The preferred approach is to use `PrasBase` and `BaseUser` to ensure smooth integration with PRAS’s functionality. However, if you choose to use other base classes, you must manually enable the serialization feature with the above method.
---
### Session Management
**PRASAlchemy provides efficient session management with automatic transaction handling for SQLAlchemy sessions:**
#### Key Concepts
- **`session_scope`**: A context manager that facilitates automatic transaction handling for SQLAlchemy sessions. It commits the session if no exceptions occur and rolls back the transaction if an exception is raised.
- **`get_session`**: Returns a new session object for database operations.
- **`close`**: Closes the specified session.
#### Usage
##### Using the Context Manager
```python
from pras.session import SQLAlchemySessionManager
session_manager = SQLAlchemySessionManager()
with session_manager.session_scope() as session:
user = session.query(User).first()
user.email = "new@email.com"
# Automatically commits if no exception occurs; rolls back if an exception occurs.
```
###### `Manual Session Management`
```python
from pras.session import SQLAlchemySessionManager
session_manager = SQLAlchemySessionManager()
session = session_manager.get_session()
try:
user = session.query(User).first()
user.email = "new@email.com"
session.commit() # Explicitly commit the session
except Exception as e:
session.rollback() # Rollback on exception
raise e
finally:
session_manager.close(session) # Ensure the session is closed
```
---
### Tokenization
**PrasBridge provides robust tokenization features for generating secure tokens and user-friendly slugs.**
#### Token Generation
##### `make_token`
| **Argument** | **Type** | **Required** | **Default** | **Description** |
|--------------|----------|--------------|-------------|------------------|
| `length` | `int` | `False` | `32` | The length of the generated token. |
| `numb` | `bool` | `False` | `True` | Include numbers in the token. |
| `lower` | `bool` | `False` | `True` | Include lowercase letters in the token. |
| `upper` | `bool` | `False` | `True` | Include uppercase letters in the token. |
##### Example
```python
from pras.hashers import make_token
# Generate a secure token with specified options
token = make_token(length=10, numb=False, lower=True, upper=True)
print(token) # Example output: 'aBcDeFgHiJ'
```
#### Slug Generation
##### `slugify`
| **Argument** | **type** | **Required** | **Default** | **Description** |
| --- | --- | --- | --- | --- |
| `title` | `str` | `True` | `None` | The title to be slugified. |
| `rand` | `bool` | `False` | `False` | Add random string to the slug. |
| `rand_len` | `int` | `False` | `10` | Length of random string. |
| `dt` | `bool` | `False` | `False` | Include current datetime in the slug. |
| `ms` | `bool` | `False` | `False` | Include milliseconds in the slug. |
| `structure` | `str` | `False` | `'title-rand'` | Structure of the slug (order of elements). |
| `sep` | `str` | `False` | `'-'` | Separator used in the slug. |
| `case` | `bool` | `False` | `False` | Preserve the original case of the `title`; if `False`, convert to lowercase. |
| `spchar` | `bool` | `False` | `False` | Include special characters in the slug. |
##### Example
```python
from pras.hashers import slugify
# Basic slug generation
slug = slugify("My Blog Post") # Result: 'my-blog-post'
# Advanced slug generation with multiple options
slug = slugify(
"My Blog Post",
rand=True, # Add random string
rand_len=10, # Length of random string
dt=True, # Add current datetime
ms=True, # Include milliseconds
structure='title-dt-rand-ms', # Define slug structure
sep='-', # Use '-' as separator
case=True, # Preserve original case
spchar=False # Exclude special characters
)
print(slug) # Example output: 'My-Blog-Post-20241028-142837-KtFf1-RFAAa-1730104117955'
```
---
### Template Tags
**PrasBridge provides a set of template tags to easily render forms and input fields with customizable options.**
#### `pInput`
Renders a specific input field with customizable options.
| **Attribute** | **Type** | **Expected** | **Required** | **Default** | **Description** |
|------------------|----------|----------------|--------------|-------------|------------------|
| `field_name` | `str` | `any` | `True` | `None` | The name of the form field. |
| `form` | `Form` | `any` | `False` | `form` | The form instance where the input field is stored. |
| `html` | `str` | `any` | `False` | `None` | Custom HTML code to render in the label tag. |
| `Class` | `str` | `any` | `False` | `None` | CSS class for the main container. |
| `style` | `str` | `any` | `False` | `None` | CSS styles for the input field. |
| `LabelClass` | `str` | `any` | `False` | `None` | CSS class for the label tag. |
| `InputClass` | `str` | `any` | `False` | `None` | CSS class for the input field. |
| `ErrorClass` | `str` | `any` | `False` | `None` | CSS class for the error message. |
| `label` | `bool` | `true or false`| `False` | `true` | Whether to render the label. |
| `error` | `bool` | `true or false`| `False` | `true` | Whether to render the error message. |
| `defaultEv` | `bool` | `true or false`| `False` | `true` | Disable default behaviors if set to `False`. |
| `placeholder` | `str` | `any` | `False` | `None` | Placeholder text for the input field. |
| `LabelText` | `str` | `any` | `False` | `None` | Text to be displayed in the label. |
| `defaultValue` | `str` | `any` | `False` | `None` | Default value for the input field. |
##### Example
```django
<!-- Load the PrasBridge template tags -->
{% load pras %}
<!-- Render an input field for email -->
{% pInput "email" -> field_name
form="form"
Class="wrapper-class"
InputClass="input-class"
LabelClass="label-class"
ErrorClass="error-class"
label="true"
error="true"
placeholder="Enter email"
LabelText="Custom Label"
%}
```
##### `pForm`
Renders the complete form with customizable options.
| **Attribute** | **Type** | **Expected** | **Required** | **Default** | **Description** |
| --- | --- | --- | --- | --- | --- |
| `form` | `Form` | `any` | `False` | `form` | The form instance to be rendered. |
| `method` | `str` | `any` | `False` | `'post'` | HTTP method for the form submission. |
| `action` | `str` | `any` | `False` | `None` | Action URL for form submission. |
| `Class` | `str` | `any` | `False` | `None` | CSS class for the main container. |
| `FormClass` | `str` | `any` | `False` | `None` | CSS class for the form element. |
| `InputClass` | `str` | `any` | `False` | `None` | CSS class for the input fields. |
| `id` | `str` | `any` | `False` | `None` | ID for the form element. |
| `ButtonLabel` | `str` | `any` | `False` | `'Submit'` | Label text for the submit button. |
| `ButtonClass` | `str` | `any` | `False` | `None` | CSS class for the submit button. |
| `LabelClass` | `str` | `any` | `False` | `None` | CSS class for label tags. |
| `ErrorClass` | `str` | `any` | `False` | `None` | CSS class for error messages. |
| `label` | `bool` | `true or false` | `False` | `true` | Whether to render labels for input fields. |
| `error` | `bool` | `true or false` | `False` | `true` | Whether to render error messages. |
| `defaultEv` | `bool` | `true or false` | `False` | `true` | Disable default behaviors if set to `False` |
##### Example
```django
<!-- Load the PrasBridge template tags -->
{% load pras %}
<!-- Render a complete form -->
{% pForm "form"
method="post"
action="/submit"
Class="form-wrapper"
FormClass="form-class"
InputClass="input-class"
ButtonLabel="Submit"
ButtonClass="btn-class"
%}
```
##### Note
- To leverage the full functionality of these tags, it is recommended to use PrasBridge-provided form fields, as they synchronize more efficiently with PrasBridge template tags. While Django form fields are supported, using PrasBridge fields allows for greater customization and compatibility.
---
## Best Practices
1. Always use PrasBridge form fields instead of Django form fields for consistent styling and functionality.
2. Use the session manager's context manager (`session_scope`) when possible for automatic transaction handling.
3. Define clear serialization schemas for different use cases.
4. Utilize the built-in user authentication forms for standard user management.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
If you encounter any problems or have questions, please:
1. Check the documentation
2. Open an issue on GitHub
3. Contact the maintainers
## Credits
**PRAS** is maintained by [**PRASSamin**](https://github.com/PRASSamin) and was created to simplify Django and SQLAlchemy integration while providing enhanced functionality for modern web applications.
Raw data
{
"_id": null,
"home_page": "https://github.com/PRASSamin/PrasBridge",
"name": "PrasBridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Pras, Django, ORM, SQLAlchemy, PrasSerializer, PrasForms, PrasToken, PrasHash, PrasBase, PrasSerializer, PrasForms, PrasToken, PrasHash, PrasBase, PrasBridge",
"author": "PRAS Samin",
"author_email": "prassamin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/db/a2/9b35f8a89a5db6bab8f41b460693f0cd5542591b94e2e6b1b942f54990a7/prasbridge-1.0.0.tar.gz",
"platform": null,
"description": "# PrasBridge\n\n## About\n**PrasBridge is a powerful Python package that seamlessly integrates Django and SQLAlchemy, providing enhanced form handling, serialization capabilities, and utility functions for building robust web applications.**\n\n[](https://badge.fury.io/py/PrasBridge)\n[](https://pypi.org/project/PrasBridge/)\n[](https://pypi.org/project/PrasBridge/)\n\n\n## Features\n\n- \ud83d\udd04 Seamless Django and SQLAlchemy Integration\n- \ud83d\udcdd Enhanced Form Fields with Extra Functionality\n- \ud83d\udd10 Built-in Authentication Forms\n- \ud83c\udfa8 Customizable Form Rendering\n- \ud83d\udce6 Flexible Model Serialization\n- \ud83d\udee0\ufe0f Utility Functions (Token Generation, Slugify)\n- \ud83d\udcbc Session Management\n- \ud83c\udff7\ufe0f Custom Template Tags\n\n## Installation\n\n```bash\npip install PrasBridge\n```\n\n## Quick Start\n\n### 1. Configure Database Connection\n\n```python\n# settings.py\nDATABASES = {\n 'sqlalchemy': {\n 'URL': 'your-database-url-here'\n }\n}\n```\n\n### 2. Config Installed App\n\n```python\n# settings.py\nINSTALLED_APPS = [\n ...\n 'pras',\n]\n```\n\n### 3. Create Models\n\n```python\n# models.py\nfrom pras.models import PrasBase, BaseUser\n\nclass User(BaseUser):\n __tablename__ = 'users'\n \n # Additional fields can be added here\n ...\n```\n\n### 4. Form Handling\n\n```python\nfrom pras.forms import CharField, EmailField, RegistrationForm\n\nclass CustomRegistrationForm(RegistrationForm):\n bio = CharField(max_length=500, required=False)\n website = CharField(max_length=200, required=False)\n \n def __init__(self, *args, **kwargs):\n super().__init__(model=User, *args, **kwargs)\n```\n\n### 5. Template Tags\n\n```django\n{% load pras %}\n\n<form method=\"post\">\n {% csrf_token %}\n {% pInput \"username\" form=form label=True error=True %}\n {% pInput \"email\" form=form InputClass=\"custom-input\" %}\n {% pInput \"password\" form=form type=\"password\" %}\n <button type=\"submit\">Submit</button>\n</form>\n```\n\n## Detailed Features\n---\n### Base Models\n**PrasBridge provides robust base models designed to streamline essential fields for various classes, supporting extensibility and ease of use in applications.**\n\n#### `PrasBase`\n`PrasBase` is a foundational model for any entity that requires automatic tracking of creation and modification timestamps. It includes the following fields:\n- `id:` Auto-generated primary key for unique identification of each instance.\n- `created_at:` Automatically stores the date and time the instance was created.\n- `updated_at:` Tracks the date and time of the most recent update to the instance.\n\n#### `BaseUser`\n`BaseUser` builds on PrasBase and provides a structured template for user models. It includes essential fields for managing user accounts and permissions:\n- `username:` Unique identifier for each user.\n- `first_name:` User\u2019s first name.\n- `last_name:` User\u2019s last name.\n- `email:` User\u2019s email address, typically also unique.\n- `password:` Stores the user\u2019s hashed password.\n- `is_active:` Boolean indicating if the account is active.\n- `is_staff:` Boolean flag for administrative permissions.\n- `is_superuser:` Boolean flag for superuser permissions.\n- `date_joined:` Timestamp indicating when the user account was created.\n- `PrasBase:` Inherits `id`, `created_at`, and `updated_at` fields from `PrasBase`.\n\nThese fields make `BaseUser` an ideal base for user authentication and authorization in applications, with built-in fields for permissions and user management.\n\n\n##### Example\n```python\nfrom pras import PrasBase, BaseUser\n\n# Custom user model inheriting from BaseUser for applications that require user profiles\nclass User(BaseUser):\n __tablename__ = 'users'\n\n # Additional fields and methods specific to User can be added here\n ...\n\n# Example model for a library system\nclass Book(PrasBase):\n __tablename__ = 'books'\n\n title = Column(String, nullable=False)\n author = Column(String, nullable=False)\n isbn = Column(String, unique=True, nullable=False)\n ...\n\n # Additional attributes and methods specific to Book can be defined here\n```\n\n##### Notes\n- `Flexibility:` Both `PrasBase` and `BaseUser` provide a flexible base structure that you can extend to suit specific application needs.\n- `Consistency:` Utilizing these models ensures that essential fields like `created_at` and `updated_at` are consistently applied across your application.\n- `Customizability:` By inheriting from these bases, additional fields can be seamlessly added to create tailored entities.\n\n---\n\n### Enhanced Form Fields\n**PrasBridge provides a suite of enhanced form fields with customizable options for common field types, including:**\n\n- `CharField`\n- `EmailField`\n- `TextAreaField`\n- `ChoiceField`\n- `CheckboxField`\n- `DateField`\n- `IntegerField`\n---\n#### Common Arguments\n**These arguments apply to all PrasBridge form fields, providing flexible customization for events, accessibility, and styling:**\n\n- **Events:** `onclick`, `onfocus`, `onblur`, `onchange` \u2013 JavaScript functions for handling user interactions.\n- **Attributes:** `required`, `disabled`, `readonly`, `autocomplete` \u2013 Common HTML attributes for form fields.\n- **Styling and Classes:** `classes`, `style`, `id` \u2013 Options to add CSS classes, inline styles, and set a unique ID.\n- **Display Options:** `label`, `label_suffix`, `help_text` \u2013 Control label visibility, label suffix, and help text for field hints.\n- **Field-Specific Options:** `initial`, `value`, `show_hidden_initial`, `localize`, `validators`, `data_attrs`, `aria_attrs` \u2013 Set initial values, localize content, and add custom validation and data attributes.\n---\n\n#### Field Types\nEach field type in PrasBridge includes arguments that are commonly defined using Django's attrs dictionary for widgets. PrasBridge fields offer these as direct arguments for ease of use.\n\n---\n\n##### CharField and EmailField\n**`CharField` and `EmailField` allow direct assignment of common attributes without defining them within `attrs={}`.**\n- **Arguments**\n - `type (CharField only):` Field type, such as \"text\", \"email\", or \"password\".\n - `placeholder:` Placeholder text within the field.\n - `max_length / min_length:` Constraints on the length of input.\n - `title:` Tooltip text.\n - `size:` Size of the input field.\n - `strip:` Strips whitespace if True.\n - `empty_value:` Value if the field is empty.\n\n- **Note**\n - `type` argument is only for CharField\n - `CharField` can be set to `email` type, `EmailField` offers enhanced validation and error handling for email input.\n\n- **Example**\n ```python\n from pras.forms.fields import CharField, EmailField\n\n class MyForm(forms.Form):\n name = CharField(\n type=\"text\", # text, email, or password\n placeholder=\"Enter your name\",\n required=True,\n ...\n )\n email = EmailField(\n placeholder=\"Enter your email\",\n ...\n )\n ```\n\n---\n\n##### TextAreaField\n**PRAS\u2019s `TextAreaField` streamlines attribute customization, bypassing the need for `attrs={}`.**\n- **Arguments**\n - `rows / cols:` Set the dimensions of the text area.\n - `placeholder:` Placeholder text for the field.\n - `max_length / min_length:` Limits on text length.\n - `size:` Size of the field.\n - `strip:` Strips whitespace if True.\n - `empty_value:` Value if the field is empty.\n\n- **Example**\n ```python\n from pras.forms.fields import TextAreaField\n\n class MyForm(forms.Form):\n bio = TextAreaField(\n rows=4,\n cols=50\n ...\n )\n ```\n---\n\n##### ChoiceField\n**ChoiceField supports predefined options without needing a widget definition.**\n\n- **Arguments**\n - `choices:` List of tuple pairs representing value-label options.\n\n- **Example**\n ```python\n from pras.forms.fields import ChoiceField\n\n class MyForm(forms.Form):\n gender = ChoiceField(\n choices=[('Male', 'Male'), ('Female', 'Female')],\n ...\n )\n ```\n\n---\n\n##### CheckboxField\n**PRAS\u2019s CheckboxField allows easy configuration of checked status.**\n- **Arguments**\n - `checked:` Boolean, if True, checkbox appears selected.\n\n- **Example**\n ```python\n from pras.forms.fields import CheckboxField\n\n class MyForm(forms.Form):\n agree = CheckboxField(\n checked=True,\n ...\n )\n ```\n---\n\n##### DateField\n**DateField supports date input with optional format validation.**\n- **Arguments**\n - `input_formats:` List of accepted date formats for validation.\n\n- **Example**\n ```python\n from pras.forms.fields import DateField\n\n class MyForm(forms.Form):\n birthdate = DateField(\n input_formats=[\"%Y-%m-%d\"],\n ...\n )\n ```\n\n##### IntegerField\n**IntegerField provides constraints and step control for numeric inputs.**\n- **Arguments**\n - `min_value / max_value:` Limits for accepted values.\n - `step:` Increment step size\n\n- **Example**\n ```python\n from pras.forms.fields import IntegerField\n\n class MyForm(forms.Form):\n age = IntegerField(\n min_value=18,\n max_value=100,\n step=1,\n ...\n )\n ```\n\n### Built-in Forms\n**PrasBridge Provides built-in forms for common authentication and registration.**\n\n- **AuthenticationForm**\n- **RegistrationForm**\n\nThese forms handle the save functionality after cleaning and validating user input. However, both forms require a valid user model to function correctly\u2014without one, they will raise an error. To use these forms, pass a valid model upon creation. If you need to modify the save functionality, you can override the save method.\n\n---\n\n#### Example\n```python\n# forms.py\nfrom pras.forms import AuthenticationForm, RegistrationForm\nfrom pras.forms.fields import CharField\nfrom .models import User \n\n# Extending the AuthenticationForm\nclass MyAuthenticationForm(AuthenticationForm):\n confirm_password = CharField(\n type=\"password\",\n placeholder=\"Confirm password\",\n required=True\n )\n\n def __init__(self, *args, **kwargs):\n # Pass a valid user model for `save` functionality\n super().__init__(model=User, *args, **kwargs)\n\n\n# views.py\nfrom .forms import MyAuthenticationForm\nfrom .models import User \nfrom pras.forms import AuthenticationForm\n\ndef login(request):\n # Custom form instance with a specified model\n form = MyAuthenticationForm(\n model=User, # Optional if the model is set in the form class\n data=request.POST or None\n )\n\n # Alternatively, use the main AuthenticationForm without extending it\n form = AuthenticationForm(model=User, data=request.POST or None)\n\n if form.is_valid():\n form.save() # Completes the login process with a valid User model\n\n return render(request, 'login.html', {'form': form})\n\n# Same for RegistrationForm also you need to pass a valid user model for `save` functionality like above\n```\n\n#### Note\n- **The same usage applies for `RegistrationForm` as it does for `AuthenticationForm`:** Both forms require a valid user model to utilize the save functionality, whether you\u2019re using them directly or extending them.\n\n- **Best Practice for Extending Forms:** When extending `AuthenticationForm`, `RegistrationForm`, or any other form within PRAS, it\u2019s recommended to use the form fields provided by PrasBridge (`CharField`, `EmailField`, etc.) rather than Django\u2019s built-in fields. These PrasBridge fields offer enhanced functionality with common arguments that streamline the configuration of attributes, keeping the implementation consistent with the PrasBridge other features. Additionally, PrasBridge\u2019s fields are essential for compatibility with other PrasBridge-specific features, such as custom tags, ensuring seamless integration and 100% compatibility across all functionalities.\n\n---\n### Serialization\n\n**PrasBridge provides flexible serialization options for your models:**\n\n#### Key Concepts\n\n- **Serialization Prefix**: Use a specific prefix when defining serialization schemas. For example, use `PRAS_` as the prefix for your schemas, such as `PRAS_BasicInfo`.\n\n- **Identifier Field**: The identifier field is crucial for defining serialization schemas. This unique field allows you to access the serialized data from the model using the `to_dict` method. You must pass the identifier to `to_dict` to serialize the data according to the specified schema.\n\n- **Fields**: The `fields` attribute is used to define which fields to serialize. It accepts three types of patterns:\n - `__all__`: Includes all fields. (default).\n - `username`: Serializes and returns only the `username` field data.\n - `!field_name`: Excludes the specified field from serialization. For example, use `!password` to exclude the password field.\n\n##### Example\n```python\nfrom pras.models import BaseUser\n\nclass User(BaseUser):\n __tablename__ = 'users'\n # Define fields for the model\n\n # Define serialization schemas\n class PRAS_AllInfo:\n __identifier__ = 'allinfo'\n fields = ['__all__'] # Returns all data of the model\n \n class PRAS_UsernameInfo:\n __identifier__ = 'specific'\n fields = ['username'] # Returns only the username field data\n \n class PRAS_ExcludeInfo:\n __identifier__ = 'exclude'\n fields = ['!password'] # Returns all data except the password field\n\n# Usage\nuser = User.query.first()\nall_info = user.to_dict('allinfo') # All user data\nusername_info = user.to_dict('specific') # Only username data\nexclude_info = user.to_dict('exclude') # All data except password\n```\n\n- **Serializing Related Models**: To serialize related models, define a serialization pattern for related fields. For instance, if a model has a field `user = relationship(User)`, you need to specify the fields you wish to include.\n\n - **Supported Patterns**:\n\n - `__all__`: Include all fields of the related model.\n - `!field_name`: Exclude specified fields.\n - `field_name`: Include only that specific field.\n\n##### Example\n```python\nfrom pras.models import PrasBase, BaseUser\n\nclass User(BaseUser):\n __tablename__ = 'users'\n # Define fields for the user model\n ...\n\nclass Book(PrasBase):\n __tablename__ = 'books'\n\n user_id = Column(Integer, ForeignKey('users.id'))\n user = relationship(User)\n ...\n\n # Define serialization schema\n class PRAS_BookInfo:\n __identifier__ = 'bookinfo'\n user = ['username', 'email'] # Returns only username and email of the related user named field\n fields = ['__all__'] # Returns all data of the Book model\n\n# Usage\nbook = Book.query.first()\nbook_info = book.to_dict('bookinfo') # Serializes book data along with specified user fields\n```\n\n##### Serializing Without `PrasBase` or `BaseUser`\nWhile `PrasBase` and `BaseUser` are designed for seamless integration with PrasBridge serialization features with SQLAlchemy, you can enable serialization for models that don\u2019t use them by implementing the following:\n\n```python\nfrom pras.serializers import PrasSerializer, IntegratedMeta # Import PrasSerializer and IntegratedMeta\nfrom sqlalchemy.ext.declarative import declarative_base # Import SQLAlchemy's declarative base\n\nBase = declarative_base(metaclass=IntegratedMeta) # Pass IntegratedMeta to sync PrasBridge serialization\n\nclass MyModel(Base, PrasSerializer): # Inherit Base and PrasSerializer\n __tablename__ = 'users'\n ...\n\n\n class PRAS_BookInfo:\n __identifier__ = 'bookinfo'\n fields = ['__all__']\n```\n##### Note\n- The preferred approach is to use `PrasBase` and `BaseUser` to ensure smooth integration with PRAS\u2019s functionality. However, if you choose to use other base classes, you must manually enable the serialization feature with the above method.\n\n---\n### Session Management\n\n**PRASAlchemy provides efficient session management with automatic transaction handling for SQLAlchemy sessions:**\n\n#### Key Concepts\n- **`session_scope`**: A context manager that facilitates automatic transaction handling for SQLAlchemy sessions. It commits the session if no exceptions occur and rolls back the transaction if an exception is raised.\n- **`get_session`**: Returns a new session object for database operations.\n- **`close`**: Closes the specified session.\n\n#### Usage\n\n##### Using the Context Manager\n```python\nfrom pras.session import SQLAlchemySessionManager\n\nsession_manager = SQLAlchemySessionManager()\n\nwith session_manager.session_scope() as session:\n user = session.query(User).first()\n user.email = \"new@email.com\"\n # Automatically commits if no exception occurs; rolls back if an exception occurs.\n```\n###### `Manual Session Management`\n```python\nfrom pras.session import SQLAlchemySessionManager\n\nsession_manager = SQLAlchemySessionManager()\nsession = session_manager.get_session()\ntry:\n user = session.query(User).first()\n user.email = \"new@email.com\"\n session.commit() # Explicitly commit the session\nexcept Exception as e:\n session.rollback() # Rollback on exception\n raise e \nfinally:\n session_manager.close(session) # Ensure the session is closed\n```\n---\n### Tokenization\n\n**PrasBridge provides robust tokenization features for generating secure tokens and user-friendly slugs.**\n\n#### Token Generation\n\n##### `make_token`\n\n| **Argument** | **Type** | **Required** | **Default** | **Description** |\n|--------------|----------|--------------|-------------|------------------|\n| `length` | `int` | `False` | `32` | The length of the generated token. |\n| `numb` | `bool` | `False` | `True` | Include numbers in the token. |\n| `lower` | `bool` | `False` | `True` | Include lowercase letters in the token. |\n| `upper` | `bool` | `False` | `True` | Include uppercase letters in the token. |\n\n##### Example\n```python\nfrom pras.hashers import make_token\n\n# Generate a secure token with specified options\ntoken = make_token(length=10, numb=False, lower=True, upper=True)\n\nprint(token) # Example output: 'aBcDeFgHiJ'\n```\n\n#### Slug Generation\n##### `slugify`\n| **Argument** | **type** | **Required** | **Default** | **Description** |\n| --- | --- | --- | --- | --- |\n| `title` | `str` | `True` | `None` | The title to be slugified. |\n| `rand` | `bool` | `False` | `False` | Add random string to the slug. |\n| `rand_len` | `int` | `False` | `10` | Length of random string. |\n| `dt` | `bool` | `False` | `False` | Include current datetime in the slug. |\n| `ms` | `bool` | `False` | `False` | Include milliseconds in the slug. |\n| `structure` | `str` | `False` | `'title-rand'` | Structure of the slug (order of elements). |\n| `sep` | `str` | `False` | `'-'` | Separator used in the slug. |\n| `case` | `bool` | `False` | `False` | Preserve the original case of the `title`; if `False`, convert to lowercase. |\n| `spchar` | `bool` | `False` | `False` | Include special characters in the slug. |\n\n##### Example\n```python\nfrom pras.hashers import slugify\n\n# Basic slug generation\nslug = slugify(\"My Blog Post\") # Result: 'my-blog-post'\n\n# Advanced slug generation with multiple options\nslug = slugify(\n \"My Blog Post\",\n rand=True, # Add random string\n rand_len=10, # Length of random string\n dt=True, # Add current datetime\n ms=True, # Include milliseconds\n structure='title-dt-rand-ms', # Define slug structure\n sep='-', # Use '-' as separator\n case=True, # Preserve original case\n spchar=False # Exclude special characters\n)\n\nprint(slug) # Example output: 'My-Blog-Post-20241028-142837-KtFf1-RFAAa-1730104117955'\n```\n---\n### Template Tags\n\n**PrasBridge provides a set of template tags to easily render forms and input fields with customizable options.**\n\n\n#### `pInput`\n\nRenders a specific input field with customizable options.\n\n| **Attribute** | **Type** | **Expected** | **Required** | **Default** | **Description** |\n|------------------|----------|----------------|--------------|-------------|------------------|\n| `field_name` | `str` | `any` | `True` | `None` | The name of the form field. |\n| `form` | `Form` | `any` | `False` | `form` | The form instance where the input field is stored. |\n| `html` | `str` | `any` | `False` | `None` | Custom HTML code to render in the label tag. |\n| `Class` | `str` | `any` | `False` | `None` | CSS class for the main container. |\n| `style` | `str` | `any` | `False` | `None` | CSS styles for the input field. |\n| `LabelClass` | `str` | `any` | `False` | `None` | CSS class for the label tag. |\n| `InputClass` | `str` | `any` | `False` | `None` | CSS class for the input field. |\n| `ErrorClass` | `str` | `any` | `False` | `None` | CSS class for the error message. |\n| `label` | `bool` | `true or false`| `False` | `true` | Whether to render the label. |\n| `error` | `bool` | `true or false`| `False` | `true` | Whether to render the error message. |\n| `defaultEv` | `bool` | `true or false`| `False` | `true` | Disable default behaviors if set to `False`. |\n| `placeholder` | `str` | `any` | `False` | `None` | Placeholder text for the input field. |\n| `LabelText` | `str` | `any` | `False` | `None` | Text to be displayed in the label. |\n| `defaultValue` | `str` | `any` | `False` | `None` | Default value for the input field. |\n\n##### Example\n```django\n<!-- Load the PrasBridge template tags -->\n{% load pras %}\n\n<!-- Render an input field for email -->\n{% pInput \"email\" -> field_name\n form=\"form\" \n Class=\"wrapper-class\"\n InputClass=\"input-class\"\n LabelClass=\"label-class\"\n ErrorClass=\"error-class\"\n label=\"true\"\n error=\"true\"\n placeholder=\"Enter email\"\n LabelText=\"Custom Label\"\n%}\n```\n\n##### `pForm`\nRenders the complete form with customizable options.\n| **Attribute** | **Type** | **Expected** | **Required** | **Default** | **Description** |\n| --- | --- | --- | --- | --- | --- |\n| `form` | `Form` | `any` | `False` | `form` | The form instance to be rendered. |\n| `method` | `str` | `any` | `False` | `'post'` | HTTP method for the form submission. |\n| `action` | `str` | `any` | `False` | `None` | Action URL for form submission. |\n| `Class` | `str` | `any` | `False` | `None` | CSS class for the main container. |\n| `FormClass` | `str` | `any` | `False` | `None` | CSS class for the form element. |\n| `InputClass` | `str` | `any` | `False` | `None` | CSS class for the input fields. |\n| `id` | `str` | `any` | `False` | `None` | ID for the form element. |\n| `ButtonLabel` | `str` | `any` | `False` | `'Submit'` | Label text for the submit button. |\n| `ButtonClass` | `str` | `any` | `False` | `None` | CSS class for the submit button. |\n| `LabelClass` | `str` | `any` | `False` | `None` | CSS class for label tags. |\n| `ErrorClass` | `str` | `any` | `False` | `None` | CSS class for error messages. |\n| `label` | `bool` | `true or false` | `False` | `true` | Whether to render labels for input fields. |\n| `error` | `bool` | `true or false` | `False` | `true` | Whether to render error messages. |\n| `defaultEv` | `bool` | `true or false` | `False` | `true` | Disable default behaviors if set to `False` |\n\n##### Example\n```django\n<!-- Load the PrasBridge template tags -->\n{% load pras %}\n\n<!-- Render a complete form -->\n{% pForm \"form\" \n method=\"post\"\n action=\"/submit\"\n Class=\"form-wrapper\"\n FormClass=\"form-class\"\n InputClass=\"input-class\"\n ButtonLabel=\"Submit\"\n ButtonClass=\"btn-class\"\n%}\n\n```\n##### Note\n- To leverage the full functionality of these tags, it is recommended to use PrasBridge-provided form fields, as they synchronize more efficiently with PrasBridge template tags. While Django form fields are supported, using PrasBridge fields allows for greater customization and compatibility.\n\n---\n\n## Best Practices\n\n1. Always use PrasBridge form fields instead of Django form fields for consistent styling and functionality.\n2. Use the session manager's context manager (`session_scope`) when possible for automatic transaction handling.\n3. Define clear serialization schemas for different use cases.\n4. Utilize the built-in user authentication forms for standard user management.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nIf you encounter any problems or have questions, please:\n1. Check the documentation\n2. Open an issue on GitHub\n3. Contact the maintainers\n\n## Credits\n\n**PRAS** is maintained by [**PRASSamin**](https://github.com/PRASSamin) and was created to simplify Django and SQLAlchemy integration while providing enhanced functionality for modern web applications.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PrasBridge: Simplify project development with a powerful toolkit for integrating SQLAlchemy with Django-style features. Offers serializers, enhanced forms, token generation, hashing, ready-to-use base models and more features. perfect for projects using SQLAlchemy as the main ORM.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/PRASSamin/PrasBridge"
},
"split_keywords": [
"pras",
" django",
" orm",
" sqlalchemy",
" prasserializer",
" prasforms",
" prastoken",
" prashash",
" prasbase",
" prasserializer",
" prasforms",
" prastoken",
" prashash",
" prasbase",
" prasbridge"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dba29b35f8a89a5db6bab8f41b460693f0cd5542591b94e2e6b1b942f54990a7",
"md5": "4b441efa1c7644fddd63d18f6a192274",
"sha256": "d54ab5eb02443cab874067627deed12d7e2f3b31f18f091252a5656522f4613a"
},
"downloads": -1,
"filename": "prasbridge-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4b441efa1c7644fddd63d18f6a192274",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 30018,
"upload_time": "2024-10-28T13:17:28",
"upload_time_iso_8601": "2024-10-28T13:17:28.761209Z",
"url": "https://files.pythonhosted.org/packages/db/a2/9b35f8a89a5db6bab8f41b460693f0cd5542591b94e2e6b1b942f54990a7/prasbridge-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 13:17:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PRASSamin",
"github_project": "PrasBridge",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "prasbridge"
}
JSON
