Metadata-Version: 2.4
Name: brickdjango
Version: 0.3.2
Summary: Django project scaffolding: clean project structure in one command. Easy to use, modular layout (apps, config, settings), supports venv, pipenv, poetry, uv.
Author: Amol Balpande
Author-email: Amol Balpande <amolbalpande2020@gmail.com>
Keywords: django,django project structure,django scaffolding,django starter,django boilerplate,project structure,modular django,django cli,easy django
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: Django>=4.0
Dynamic: author
Dynamic: requires-python

# BrickDjango – Django project structure made easy

**BrickDjango** is a Django project scaffolding tool that sets up a **clean, modular project structure** in one command. Create Django projects and apps with a scalable layout (config, apps, settings split by environment), environment variables, and optional Docker—**easy to use** on Windows, Linux, and macOS.

> **Django project structure** • **Django scaffolding** • **Django starter** • **Modular Django** • One-command setup

---

## Table of Contents

1. [Introduction](#-introduction)
2. [Installation](#-installation)
3. [Features](#-features)
4. [Quick Start](#-quick-start)
5. [Creating a New Project](#-creating-a-new-project)
6. [Creating a New App](#-creating-a-new-app)
7. [Project Structure](#-project-structure)
8. [Settings Management](#-settings-management)
9. [Best Practices](#-best-practices)
10. [Troubleshooting](#-troubleshooting)
11. [Testing the project locally](#-testing-the-project-locally)
12. [Author](#-author)

---

## Introduction

**BrickDjango** gives you a **professional Django project structure** without manual setup. One command creates the folder layout, virtual environment, split settings (development/production), and `.env` for secrets—so you can start coding instead of wiring config.

- **Brick** — the building block: modularity, foundation, simplicity.
- **Django** — the Python web framework you already use.

**Why BrickDjango?**
- **Easy to use** — `brickdjango startproject myapp` and you get a ready-to-run project.
- **Clear project structure** — `apps/` for your apps, `config/settings/` for base/dev/prod, `base/` for shared code.
- **Flexible** — choose venv, pipenv, poetry, or uv; works on any OS.
- **Scalable** — layout that stays clean as the project grows.

---

## Installation

### Requirements

- Python 3.8 or higher
- pip (Python package manager)

### Install from PyPI

```bash
pip install brickdjango
```

### CLI options

After installation, the `brickdjango` command is available:

```bash
brickdjango --version   # or -v
brickdjango --help      # or -h
```

---

## Features

- **Easy Django project structure** — one command creates a modular layout: `apps/`, `config/`, `base/`
- **Cross-platform** — works on Windows, Linux, and macOS (paths, venv Scripts/bin, UTF-8 file I/O)
- **Modular project layout** — `apps/` for apps, `config/settings/` for base/development/production, `base/` for shared code
- **CLI** — `startproject` and `startapp` with a single command (startapp is project-independent, like `django-admin startapp`)
- **Automatic app namespacing** — when run from a BrickDjango project root, apps are created as `apps.<app_name>` under `apps/`
- **Environment-based settings** — `base.py`, `development.py`, `production.py`
- **Environment variables** — `django-environ` and `.env` in `config/settings/`
- **Docker** — generated project includes a `Dockerfile` when you choose venv or uv (it uses `requirements.txt`; pipenv/poetry projects use Pipfile/pyproject.toml instead)
- **Virtual environment** — choose **venv**, **pipenv**, **poetry**, or **uv** when creating a project; the tool creates and uses that environment and installs Django and django-environ in it

---

## Quick Start

```bash
# Create a new project (you will be asked to choose: venv, pipenv, poetry, or uv)
brickdjango startproject mysite
cd mysite

# Activate or use the environment you chose, then run the server:
#   venv:   source venv/bin/activate  (or venv\Scripts\activate on Windows), then  python manage.py runserver
#   pipenv: pipenv run python manage.py runserver  (or pipenv shell first)
#   poetry: poetry run python manage.py runserver  (or poetry shell first)
#   uv:     uv run python manage.py runserver
```

To add an app: run from any directory (like `django-admin startapp`). From a BrickDjango project root, the app is created under `apps/` and registered as `apps.<app_name>`.

```bash
brickdjango startapp blog
```

Then add the app to your settings (`CUSTOM_APPS` in a BrickDjango project, or `INSTALLED_APPS` otherwise).

---

## Creating a New Project

```bash
brickdjango startproject <project_name>
```

You will be prompted to choose a virtual environment type:

| Choice | Tool   | Description                    |
|--------|--------|--------------------------------|
| 1      | **venv**  | Standard library `venv` (default) |
| 2      | **pipenv** | [Pipenv](https://pipenv.pypa.io/) – creates Pipfile and `.venv` |
| 3      | **poetry** | [Poetry](https://python-poetry.org/) – creates `pyproject.toml` and `.venv` |
| 4      | **uv**    | [uv](https://docs.astral.sh/uv/) – creates `.venv` and installs with uv |

- **venv**: No extra install; uses the Python you run `brickdjango` with. Creates a `venv/` directory.
- **pipenv / poetry / uv**: Must be installed and on your PATH. The tool will create the project directory, then run the chosen tool there to create the environment and install Django and django-environ.

This command then:

- Creates the project directory and the chosen environment
- Installs Django and django-environ in that environment
- Runs `django-admin startproject config` to create the Django project
- Creates the BrickDjango layout (config/settings, apps, base), writes `base.py`, `development.py`, `production.py`, and `.env` (with `SECRET_KEY`)
- Adds `.gitignore`; for **venv** or **uv** also adds `requirements.txt` and `Dockerfile` (for **pipenv** or **poetry** these are omitted; use Pipfile or pyproject.toml)

**Example:**

```bash
brickdjango startproject mysite
# Enter choice (1-4) [default: 1]: 1
cd mysite
source venv/bin/activate   # or use pipenv/poetry/uv as chosen
python manage.py runserver
```

**Success output:** You will see the project path, the environment used, and next steps (how to activate/run and how to create apps).

---

## Creating a New App

```bash
brickdjango startapp <app_name>
```

**Independent of the project** — like `django-admin startapp`, this command does not require `manage.py`. You can run it from any directory. It uses Django’s `startapp` under the hood.

- **When run from a BrickDjango project root** (a directory that contains `manage.py`): the app is created inside `apps/<app_name>/`, and `apps.py` is set to `name = 'apps.<app_name>'`. Add `'apps.<app_name>'` to `CUSTOM_APPS` in `config/settings/base.py`.
- **When run from any other directory**: the app is created in the current directory as `<app_name>/`. Add `'<app_name>'` to `INSTALLED_APPS` in your Django settings.

**Example (from project root):**

```bash
cd mysite
brickdjango startapp blog
```

This creates `apps/blog/` and configures `apps/blog/apps.py` as:

```python
from django.apps import AppConfig

class BlogConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'apps.blog'
```

**Register the app** in `config/settings/base.py` by adding it to `CUSTOM_APPS`:

```python
CUSTOM_APPS = [
    'apps.blog',
]
```

(`INSTALLED_APPS` is built from `DEFAULT_APPS + THIRDPARTY_APPS + CUSTOM_APPS` in base settings.)

---

## Project Structure

BrickDjango’s project structure is simple and scalable. After `brickdjango startproject myproject`, you get:

```
myproject/
├── base/                 # For shared utilities and common code
│   └── __init__.py
├── apps/
│   └── __init__.py       # Your apps go here (e.g. apps/blog/)
├── config/
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py       # Common settings, INSTALLED_APPS, etc.
│   │   ├── development.py
│   │   ├── production.py
│   │   └── .env          # SECRET_KEY and other env vars
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── manage.py
├── requirements.txt   # only for venv/uv (pipenv/poetry use Pipfile/pyproject.toml)
├── Dockerfile         # only for venv/uv
├── .gitignore
└── venv/
```

---

## Settings Management

**Base settings are derived from the Django version installed in the project** (the one used when you run `brickdjango startproject`). The tool reads the settings file that Django generates and turns it into `config/settings/base.py` (adding environ, `SECRET_KEY` from env, and the `DEFAULT_APPS` / `CUSTOM_APPS` structure). That way you get the same defaults and any new settings that come with newer Django versions, instead of a fixed template.

Settings are split by environment:

| File             | Purpose                          |
|------------------|----------------------------------|
| `config/settings/base.py`     | Shared settings, `SECRET_KEY` from env, `INSTALLED_APPS` |
| `config/settings/development.py` | Debug, local DB, dev-only config |
| `config/settings/production.py`  | Production (e.g. `DEBUG = False`) |

The default `manage.py` uses:

```python
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.development')
```

For production, set `DJANGO_SETTINGS_MODULE=config.settings.production` (and configure `ALLOWED_HOSTS` and your database in production settings).

**Secret key:** The generated project puts `SECRET_KEY` in `config/settings/.env`. Keep `.env` out of version control.

---

## Best Practices

- From a BrickDjango project root, run `brickdjango startapp <app_name>` so apps live under `apps/` with `apps.<app_name>`.
- Register new apps only in `CUSTOM_APPS` in `config/settings/base.py`.
- Put shared code in `base/` (e.g. `base/utils/`).
- Use `development.py` for local work and `production.py` for deployment.
- Add a `.env.example` (without secrets) to the repo; keep `.env` in `.gitignore`.

---

## Troubleshooting

### "Error: A project named '...' already exists at ..."

- A directory with that project name already exists in the current folder. Choose another name or use a different parent directory.

### "Error: An app or directory named '...' already exists at ..."

- An app or folder with that name already exists at the target path (either in the current directory or under `apps/`). Choose a different app name or remove the existing folder.

### Django not found when running `startapp`

- `brickdjango startapp` runs `django-admin startapp` under the hood. Ensure Django is installed in the environment where you run `brickdjango` (e.g. `pip install brickdjango` installs Django as a dependency).

### "Error: pipenv / poetry / uv is not installed or not on PATH"

- If you chose pipenv, poetry, or uv when creating a project, that tool must be installed and available on your PATH. Install it before running `brickdjango startproject`, or choose **1 (venv)** which uses only the standard library.

---

## Testing the project locally

Use these steps to run and test the package on your machine without publishing to PyPI.

### 1. Install in editable mode

From the project root (where `setup.py` and `pyproject.toml` are):

```bash
cd /path/to/custom_package
python -m venv venv
# Activate the venv:
#   Linux/macOS: source venv/bin/activate
#   Windows:     venv\Scripts\activate
pip install -e .
```

After this, the `brickdjango` command uses your local code. Edits to the package are picked up without reinstalling.

### 2. Check the CLI

```bash
brickdjango --version
brickdjango --help
```

### 3. Test startproject

Create a test project in a temporary directory (so you can delete it after):

```bash
mkdir -p /tmp/brickdjango_test
cd /tmp/brickdjango_test
brickdjango startproject testproject
```

When prompted, choose **1 (venv)** for a quick test. Then:

```bash
cd testproject
source venv/bin/activate   # or venv\Scripts\activate on Windows
python manage.py runserver
```

Stop the server (Ctrl+C), then try `startapp` from the project directory:

```bash
cd /tmp/brickdjango_test/testproject
brickdjango startapp demo
```

Check that `apps/demo/` exists and that `config/settings/base.py` has the right structure (add `'apps.demo'` to `CUSTOM_APPS` if you want to load the app).

### 4. Clean up (optional)

```bash
rm -rf /tmp/brickdjango_test
```

---

## Author

**Amol Balpande** — [amolbalpande2020@gmail.com](mailto:amolbalpande2020@gmail.com)

BrickDjango gives you a solid foundation for scalable, maintainable Django applications. We hope it helps you build great projects — one brick at a time.
