Metadata-Version: 2.5
Name: angel727
Version: 0.1.2
Summary: Interactive Django Application Builder & Code Generator — describe it, build it.
Project-URL: Homepage, https://github.com/angel727/angel727
Project-URL: Issues, https://github.com/angel727/angel727/issues
Author: Angel727 Contributors
License: MIT
License-File: LICENSE
Keywords: cli,code-generator,django,drf,rest-framework,scaffolding
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Requires-Dist: libcst>=1.1.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2; extra == 'django'
Requires-Dist: djangorestframework>=3.14; extra == 'django'
Description-Content-Type: text/markdown

# Angel727

**Angel727 — Describe It. Build It.**

Angel727 is an interactive, keyboard-driven Django development assistant created by T.P. Thangaprabhu B.Sc., MBA., CIMA ADV DIP MA (UK), FCMA., ACPIFSD (IIT - Roorkee) — Cost Accountant | Full Stack Developer & Data Scientist.

It helps developers create and extend Django and Django REST Framework applications without manually writing repetitive boilerplate code.

Instead of remembering Django field syntax, serializer configuration, ViewSets, admin registration, URL routing, and other repetitive patterns, you describe what you want, and Angel727 guides you through a structured interactive process.

```text
USER REQUIREMENT
       ↓
INTERACTIVE WIZARD
       ↓
STRUCTURED SPECIFICATION
       ↓
VALIDATION ENGINE
       ↓
CODE GENERATORS
       ↓
SAFE SOURCE PATCHING
       ↓
PREVIEW / DIFF
       ↓
USER CONFIRMATION
       ↓
PROJECT UPDATE
```

## Why Angel727?

Django makes application development powerful and productive, but a significant amount of repetitive work is still required.

For one model, developers may need to create and maintain:

```text
models.py
admin.py
serializers.py
views.py
urls.py
forms.py
permissions.py
filters.py
validators.py
tests.py
```

Angel727 aims to reduce this repetitive work.

For example, instead of manually writing:

```python
class Customer(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
```

you can define the model interactively and let Angel727 generate the appropriate Django code.

The goal is simple: **let the developer describe the application requirement while Angel727 handles repetitive Django implementation.**

## Features

Current Angel727 functionality includes:

- Interactive Django project detection
- Keyboard-driven model wizard
- Arrow-key field selection
- Django field type selection
- Field-specific configuration
- Django-aware validation
- Structured model specifications
- Django model generation
- Django admin generation
- Django REST Framework serializer generation
- **REST API configuration wizard** — per model, choose which CRUD operations to expose (List/Retrieve/Create/Update/Delete), whether authentication is required, and which DRF permission class to use
- DRF ViewSet generation (`ModelViewSet` for full CRUD, `ReadOnlyModelViewSet` for list+retrieve only, or an explicit `GenericViewSet` + mixins for any other subset)
- URL generation
- Existing source-code inspection
- Safe source patching
- Diff preview
- Confirmation before changes
- File backups
- Undo support (reverts a whole operation at once, including files it created)
- Saved specifications
- Project inspection
- Automated tests

## Installation

Install Angel727 from PyPI:

```bash
pip install angel727
```

After installation, verify:

```bash
angel727 version
```

You can also run:

```bash
python -m angel727 version
```

## Requirements

Angel727 is designed to be lightweight. The package itself does not require Django or Django REST Framework for its core functionality.

For Django project generation, you need an existing Django project. For DRF-specific generation, Django REST Framework must be available in the target project.

Typical environment:

```text
Python 3.9+
Django
Django REST Framework (optional)
```

## Quick Start

Navigate to an existing Django project. The project should contain `manage.py`:

```text
myproject/
├── manage.py
├── myproject/
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
└── customers/
    ├── models.py
    ├── admin.py
    └── ...
```

Run:

```bash
angel727 model Customer
```

Angel727 starts the interactive model builder.

## Interactive Model Builder

Suppose you want to create `Customer` with fields `name`, `email`, `address`, `pin`.

Run:

```bash
angel727 model Customer
```

Angel727 asks for each field individually:

```text
Field name: name
```

Then:

```text
What type is "name"?

❯ CharField
  TextField
  EmailField
  IntegerField
  DecimalField
  BooleanField
  DateField
  DateTimeField
  UUIDField
  ForeignKey
  OneToOneField
  ManyToManyField
  FileField
  ImageField
  JSONField

↑ ↓ Navigate    Enter Select
```

Use `↑`/`↓` to move, `Enter` to select, `Esc` to go back. There is no need to remember numeric menu choices.

## Field Configuration

After selecting a field type, Angel727 asks only the questions relevant to that field.

For a `CharField`:

```text
Maximum length?
Required?
Allow NULL?
Allow blank?
Unique?
Database index?
```

Other applicable options may include default value, help text, verbose name, and database column name. Angel727 does not ask irrelevant questions for field types where those options do not apply.

## Intelligent Field Recommendations

Angel727 can provide recommendations based on the meaning of a field name.

For example, `pin` may look numeric, but a PIN is normally an identifier rather than a mathematical number, and may contain leading zeros (`012345`). Angel727 recommends `CharField` with optional numeric validation instead of automatically choosing `IntegerField`.

Similarly, fields such as `phone`, `mobile`, `postal_code`, `zip_code`, `amount`, and `percentage` get type recommendations based on their name. The user always remains in control and can choose a different field type.

## Supported Django Field Types

Angel727 supports the core Django field types used by the model builder, including:

```text
AutoField            BigAutoField          BigIntegerField
BinaryField          BooleanField          CharField
TextField            EmailField            IntegerField
PositiveIntegerField PositiveSmallIntegerField SmallIntegerField
PositiveBigIntegerField FloatField         DecimalField
DateField            DateTimeField         TimeField
DurationField        UUIDField             SlugField
URLField             GenericIPAddressField FileField
ImageField           JSONField             ForeignKey
OneToOneField        ManyToManyField
```

The field system is designed to be extensible.

## ForeignKey Support

For a `ForeignKey`, Angel727 asks for the related model, then:

```text
on_delete:

❯ CASCADE
  PROTECT
  SET_NULL
  SET_DEFAULT
  RESTRICT
  DO_NOTHING
```

Additional relationship settings can include `related_name`, `related_query_name`, `null`, `blank`, `default`, and `db_index`.

Angel727 validates relationships before generating code. For example, choosing `on_delete = SET_NULL` automatically enforces `null=True` on that field.

## Structured Specification

Angel727 does not directly convert user input into arbitrary Python code. Instead, it first creates a structured specification:

```json
{
  "model": "Customer",
  "fields": [
    {
      "name": "name",
      "type": "CharField",
      "options": {
        "max_length": 100,
        "blank": false,
        "null": false,
        "unique": false,
        "db_index": false
      }
    },
    {
      "name": "email",
      "type": "EmailField",
      "options": { "unique": true, "blank": false, "null": false }
    }
  ]
}
```

This structured specification becomes the source of truth. The generators then use it to produce the appropriate Django code.

## Code Generation

From a model specification, Angel727 generates coordinated Django components.

**models.py**

```python
class Customer(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
    address = models.CharField(max_length=500)
    pin = models.CharField(max_length=6)
```

**admin.py**

```python
@admin.register(Customer)
class CustomerAdmin(admin.ModelAdmin):
    list_display = ("name", "email", "address", "pin")
    search_fields = ("name", "email")
```

**serializers.py** (when Django REST Framework is detected)

```python
class CustomerSerializer(serializers.ModelSerializer):
    class Meta:
        model = Customer
        fields = "__all__"
```

**views.py**

Before generating the ViewSet, Angel727 asks:

```text
? Enable REST API for Product? Yes
? Which operations?
  ☑ List
  ☑ Retrieve
  ☑ Create
  ☑ Update
  ☑ Delete
? Authentication required? Yes
? Permission?
  ❯ IsAuthenticated
    AllowAny
    IsAdminUser
    IsAuthenticatedOrReadOnly
```

With every operation selected, this generates:

```python
class CustomerViewSet(viewsets.ModelViewSet):
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer
    authentication_classes = [SessionAuthentication, TokenAuthentication]
    permission_classes = [IsAuthenticated]
```

If only some operations are selected — say List, Retrieve, Create, Update but not Delete — Angel727 does **not** hand you a full `ModelViewSet` with a delete endpoint you didn't ask for. It generates an explicit mixin-based ViewSet instead:

```python
class ProductViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin,
                      mixins.CreateModelMixin, mixins.UpdateModelMixin,
                      viewsets.GenericViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    authentication_classes = [SessionAuthentication, TokenAuthentication]
    permission_classes = [IsAuthenticated]
```

List+Retrieve only collapses to `viewsets.ReadOnlyModelViewSet`. If authentication is not required, `authentication_classes` is omitted and the chosen permission (typically `AllowAny`) is used as-is.

**urls.py** (DRF router)

```python
router.register("customers", CustomerViewSet, basename="customer")
```

Existing routes are preserved. Duplicate registrations are not created.

## Existing Project Safety

Angel727 is designed to work with existing Django projects. It does not blindly replace entire source files.

Before modifying a file, Angel727:

1. Inspects the existing file
2. Detects existing code
3. Validates the requested change
4. Prepares a minimal modification
5. Displays the proposed diff
6. Creates a backup
7. Asks for confirmation
8. Applies the change

For example, if `admin.py` already contains a `UserAdmin` registration and you create `Customer`, Angel727 adds the `Customer` registration without disturbing the existing `User` registration.

## Preview and Diff

Before writing files, Angel727 shows what will change:

```text
Files to modify:

  models.py        +7
  admin.py         +8
  serializers.py   +8
  views.py         +8
  urls.py          +7
```

followed by a unified diff of each changed file, so you can review before anything is applied.

## Confirmation Before Writing

Angel727 does not silently modify the project:

```text
Proceed?

❯ Generate
  Edit
  Cancel
```

Only after confirmation are changes written.

## Backups

Before modifying project files, Angel727 creates backups under:

```text
.angel727/
└── backups/
```

This provides a recovery mechanism for changes made by Angel727.

## Undo

To revert the most recent Angel727 operation:

```bash
angel727 undo
```

A single `angel727 undo` restores **every** file touched by the previous operation as one unit — files that were modified are restored to their prior content, and files that Angel727 newly created are removed.

## Specifications

Angel727 stores structured specifications under:

```text
.angel727/
└── specifications/
    ├── customer.json
    ├── product.json
    └── invoice.json
```

This allows generated models to be reviewed, saved, edited, validated, and regenerated later.

## Project Inspection

Run:

```bash
angel727 inspect
```

Angel727 inspects the Django project and reports:

```text
+======================================+
|              ANGEL727                |
|  Django Application Builder          |
+======================================+

Project: myproject
Django: detected
DRF: detected
```

plus any saved specifications found under `.angel727/specifications/`.

## Command Line Commands

**Start Angel727**

```bash
angel727
```

Running Angel727 without arguments opens the interactive main menu.

| Command | Description |
|---|---|
| `angel727 init` | Scaffold `.angel727/` in the current Django project |
| `angel727 inspect` | Show detected project facts |
| `angel727 model Customer` | Create/extend a model and generate coordinated files |
| `angel727 preview Customer` | Preview changes for a saved specification, without writing anything |
| `angel727 diff Customer` | Alias for `preview` |
| `angel727 generate Customer` | Regenerate files from a saved specification |
| `angel727 validate Customer` | Re-check a saved specification for consistency |
| `angel727 undo` | Revert the previous Angel727 operation |
| `angel727 version` | Show the installed version |

Every command above has been run against a real (synthetic) Django project as part of this release's test pass — see **Current Status**.

## Project Architecture

Angel727 follows a layered architecture:

```text
                   Angel727
                       │
                       ↓
               Interactive Wizard
                       │
                       ↓
              Structured Schema
                       │
                       ↓
              Validation Engine
                       │
                       ↓
                Code Generators
                       │
                       ↓
               Source Analysis
                       │
                       ↓
                Safe Patching
                       │
                       ↓
                Diff / Preview
                       │
                       ↓
                 User Approval
                       │
                       ↓
               Django Project
```

The wizard never writes Python code directly — everything passes through the structured specification first.

## Package Architecture

```text
angel727/
└── src/
    └── angel727/
        ├── cli.py
        ├── version.py
        ├── django/
        │   ├── field_types.py
        │   └── rules.py
        ├── files/
        │   ├── backup.py
        │   ├── manager.py
        │   └── undo.py
        ├── generators/
        │   ├── base.py
        │   ├── models.py
        │   ├── admin.py
        │   ├── serializers.py
        │   ├── views.py
        │   └── urls.py
        ├── project/
        │   └── detector.py
        ├── schema/
        │   ├── field.py
        │   ├── model.py
        │   └── specification.py
        ├── source/
        │   ├── diff.py
        │   └── patcher.py
        ├── specifications/
        ├── utils/
        └── wizard/
            ├── field_wizard.py
            ├── menu.py
            └── model_wizard.py
```

## Generator Architecture

```text
schema
   │
   ├──────────────┐
   ↓              ↓
Model          Field
Specification  Specification
   │
   ↓
Generators
   │
   ├── models.py
   ├── admin.py
   ├── serializers.py
   ├── views.py
   └── urls.py
```

The generator layer is deliberately separated from the interactive wizard, so new generators can be added without redesigning the model builder.

## Source Patching

The source layer is responsible for import handling, existing-class detection, safe modifications, and diff generation, using LibCST rather than naive string concatenation — the goal is targeted changes, not full-file replacement.

## Design Principle

Angel727 is not simply:

```text
AI → Python
```

Instead:

```text
Requirement
     ↓
Structured Specification
     ↓
Django-aware Validation
     ↓
Code Generator
     ↓
Source Analysis
     ↓
Safe Patch
     ↓
Preview
     ↓
Confirmation
     ↓
Project Update
```

This makes the generated code predictable, inspectable, and maintainable.

## Current Status — Version 0.1.0

Angel727 0.1.0 establishes the core architecture and initial Django development workflow.

**Verified working** in this release:

```text
angel727 version
angel727 inspect
angel727 model Customer
angel727 preview Customer
angel727 validate Customer
angel727 undo
```

manually exercised against a synthetic Django project, and the full `angel727 model Product` flow — including the REST API configuration wizard with a partial CRUD selection (List/Retrieve/Create/Update, Delete excluded) — was additionally verified against a **real** Django + DRF project created with `django-admin startproject` / `startapp`:

```text
python manage.py check     -> System check identified no issues (0 silenced).
python manage.py migrate   -> Applying crm.0001_initial... OK
```

and the generated `ProductViewSet` was exercised at runtime with DRF's `APIRequestFactory`: unauthenticated requests correctly returned `403`, authenticated requests returned `200`, and `hasattr(ProductViewSet, "destroy")` was confirmed `False` since Delete was not selected.

Also implemented: project detection, arrow-key navigation, field-specific configuration, structured specifications, Django-aware validation, admin/serializer/ViewSet/URL generation, source patching, diff/preview, and file backups.

The automated test suite contains 37 tests, and it currently passes:

```text
37 passed
```

## Roadmap

Angel727 is intended to grow into a complete Django application development assistant.

**Django Components:** `forms.py`, `permissions.py`, `filters.py`, `validators.py`, `services.py`, `managers.py`, `signals.py`, `tests.py`

**Project Configuration:** `settings.py`, project `urls.py`, database configuration, authentication, email, static/media files, caching, Celery, Redis

**Developer Features:** deeper source analysis, more advanced diffing, refactoring support, automatic test generation, migration assistance

**Natural Language (future):** requirements described in plain English, converted into a structured specification before any code is generated — the specification layer stays authoritative

**Optional AI (future):** requirement interpretation, field recommendations, business-rule suggestions, code explanations, documentation, test generation, refactoring — always optional, never bypassing the deterministic validation layer

## Development

```bash
python -m pip install -e .
python -m pytest
```

Expected result:

```text
37 passed
```

## Building the Package

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

This creates:

```text
dist/
├── angel727-0.1.0-py3-none-any.whl
└── angel727-0.1.0.tar.gz
```

## Release

```bash
pip install angel727
```

## Contributing

Contributions, suggestions, bug reports, and feature requests are welcome. When contributing:

- Keep the architecture modular
- Do not bypass the structured specification layer
- Do not introduce unsafe source modifications
- Preserve existing project code
- Add tests for new functionality
- Run the complete test suite before submitting changes

## Security

Angel727 modifies source code and project files. Review generated changes before applying them, particularly in production projects.

Do not store passwords, API keys, database credentials, private tokens, or other secrets inside generated source code — use environment variables and appropriate Django configuration for sensitive values.

## License

Angel727 is released under the MIT License. See `LICENSE` for details.

## Project Vision

```text
WHAT DO YOU WANT TO BUILD?
            ↓
       ANSWER QUESTIONS
            ↓
     DEFINE THE STRUCTURE
            ↓
      ANGEL727 GENERATES
            ↓
      REVIEW THE CHANGES
            ↓
        BUILD YOUR APP
```

**Angel727 — Describe It. Build It.**
