mirror of
https://github.com/django-components/django-components.git
synced 2025-07-12 11:25:00 +00:00
8677ee7941
* refactor: deprecate template caching, get_template_name, get_template, assoc template with Comp cls * refactor: change implementation * refactor: handle cached template loader * refactor: fix tests * refactor: fix test on windows * refactor: try to fix type errors * refactor: Re-cast `context` to fix type errors * refactor: fix linter error * refactor: fix typing * refactor: more linter fixes * refactor: more linter errors * refactor: revert extra node metadata
568 lines
15 KiB
Markdown
568 lines
15 KiB
Markdown
<!-- Autogenerated by reference.py -->
|
|
|
|
# Commands
|
|
|
|
These are all the [Django management commands](https://docs.djangoproject.com/en/5.2/ref/django-admin)
|
|
that will be added by installing `django_components`:
|
|
|
|
|
|
## ` components`
|
|
|
|
```txt
|
|
usage: python manage.py components [-h] {create,upgrade,ext,list} ...
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/components.py#L10" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
The entrypoint for the 'components' commands.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
|
|
**Subcommands:**
|
|
|
|
- [`create`](../commands#components-`create`)
|
|
- Create a new django component.
|
|
- [`upgrade`](../commands#components-`upgrade`)
|
|
- Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.
|
|
- [`ext`](../commands#components-`ext`)
|
|
- Run extension commands.
|
|
- [`list`](../commands#components-`list`)
|
|
- List all components created in this project.
|
|
|
|
|
|
|
|
|
|
The entrypoint for the "components" commands.
|
|
|
|
```bash
|
|
python manage.py components list
|
|
python manage.py components create <name>
|
|
python manage.py components upgrade
|
|
python manage.py components ext list
|
|
python manage.py components ext run <extension> <command>
|
|
```
|
|
|
|
|
|
## `components create`
|
|
|
|
```txt
|
|
usage: python manage.py components create [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose] [--dry-run] name
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/create.py#L11" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Create a new django component.
|
|
|
|
**Positional Arguments:**
|
|
|
|
- `name`
|
|
- The name of the component to create. This is a required argument.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--path PATH`
|
|
- The path to the component's directory. This is an optional argument. If not provided, the command will use the `COMPONENTS.dirs` setting from your Django settings.
|
|
- `--js JS`
|
|
- The name of the JavaScript file. This is an optional argument. The default value is `script.js`.
|
|
- `--css CSS`
|
|
- The name of the CSS file. This is an optional argument. The default value is `style.css`.
|
|
- `--template TEMPLATE`
|
|
- The name of the template file. This is an optional argument. The default value is `template.html`.
|
|
- `--force`
|
|
- This option allows you to overwrite existing files if they exist. This is an optional argument.
|
|
- `--verbose`
|
|
- This option allows the command to print additional information during component creation. This is an optional argument.
|
|
- `--dry-run`
|
|
- This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is `False`.
|
|
|
|
|
|
|
|
|
|
### Usage
|
|
|
|
To use the command, run the following command in your terminal:
|
|
|
|
```bash
|
|
python manage.py components create <name> --path <path> --js <js_filename> --css <css_filename> --template <template_filename> --force --verbose --dry-run
|
|
```
|
|
|
|
Replace `<name>`, `<path>`, `<js_filename>`, `<css_filename>`, and `<template_filename>` with your desired values.
|
|
|
|
### Examples
|
|
|
|
Here are some examples of how you can use the command:
|
|
|
|
**Creating a Component with Default Settings**
|
|
|
|
To create a component with the default settings, you only need to provide the name of the component:
|
|
|
|
```bash
|
|
python manage.py components create my_component
|
|
```
|
|
|
|
This will create a new component named `my_component` in the `components` directory of your Django project. The JavaScript, CSS, and template files will be named `script.js`, `style.css`, and `template.html`, respectively.
|
|
|
|
**Creating a Component with Custom Settings**
|
|
|
|
You can also create a component with custom settings by providing additional arguments:
|
|
|
|
```bash
|
|
python manage.py components create new_component --path my_components --js my_script.js --css my_style.css --template my_template.html
|
|
```
|
|
|
|
This will create a new component named `new_component` in the `my_components` directory. The JavaScript, CSS, and template files will be named `my_script.js`, `my_style.css`, and `my_template.html`, respectively.
|
|
|
|
**Overwriting an Existing Component**
|
|
|
|
If you want to overwrite an existing component, you can use the `--force` option:
|
|
|
|
```bash
|
|
python manage.py components create my_component --force
|
|
```
|
|
|
|
This will overwrite the existing `my_component` if it exists.
|
|
|
|
**Simulating Component Creation**
|
|
|
|
If you want to simulate the creation of a component without actually creating any files, you can use the `--dry-run` option:
|
|
|
|
```bash
|
|
python manage.py components create my_component --dry-run
|
|
```
|
|
|
|
This will simulate the creation of `my_component` without creating any files.
|
|
|
|
|
|
## `components upgrade`
|
|
|
|
```txt
|
|
usage: python manage.py components upgrade [-h] [--path PATH]
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/upgrade.py#L13" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--path PATH`
|
|
- Path to search for components
|
|
|
|
|
|
|
|
|
|
|
|
## `components ext`
|
|
|
|
```txt
|
|
usage: python manage.py components ext [-h] {list,run} ...
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/ext.py#L5" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Run extension commands.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
|
|
**Subcommands:**
|
|
|
|
- [`list`](../commands#components-ext-`list`)
|
|
- List all extensions.
|
|
- [`run`](../commands#components-ext-`run`)
|
|
- Run a command added by an extension.
|
|
|
|
|
|
|
|
|
|
Run extension commands.
|
|
|
|
```bash
|
|
python manage.py components ext list
|
|
python manage.py components ext run <extension> <command>
|
|
```
|
|
|
|
|
|
## `components ext list`
|
|
|
|
```txt
|
|
usage: python manage.py components ext list [-h] [--all] [--columns COLUMNS] [-s]
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/ext_list.py#L6" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
List all extensions.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--all`
|
|
- Show all columns. Same as `--columns name`.
|
|
- `--columns COLUMNS`
|
|
- Comma-separated list of columns to show. Available columns: name. Defaults to `--columns name`.
|
|
- `-s`, `--simple`
|
|
- Only show table data, without headers. Use this option for generating machine-readable output.
|
|
|
|
|
|
|
|
|
|
List all extensions.
|
|
|
|
```bash
|
|
python manage.py components ext list
|
|
```
|
|
|
|
Prints the list of installed extensions:
|
|
|
|
```txt
|
|
name
|
|
==============
|
|
view
|
|
my_extension
|
|
```
|
|
|
|
To specify which columns to show, use the `--columns` flag:
|
|
|
|
```bash
|
|
python manage.py components ext list --columns name
|
|
```
|
|
|
|
Which prints:
|
|
|
|
```txt
|
|
name
|
|
==============
|
|
view
|
|
my_extension
|
|
```
|
|
|
|
To print out all columns, use the `--all` flag:
|
|
|
|
```bash
|
|
python manage.py components ext list --all
|
|
```
|
|
|
|
If you need to omit the title in order to programmatically post-process the output,
|
|
you can use the `--simple` (or `-s`) flag:
|
|
|
|
```bash
|
|
python manage.py components ext list --simple
|
|
```
|
|
|
|
Which prints just:
|
|
|
|
```txt
|
|
view
|
|
my_extension
|
|
```
|
|
|
|
|
|
## `components ext run`
|
|
|
|
```txt
|
|
usage: python manage.py components ext run [-h]
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/ext_run.py#L48" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Run a command added by an extension.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
|
|
|
|
|
|
|
|
Run a command added by an [extension](../../concepts/advanced/extensions).
|
|
|
|
Each extension can add its own commands, which will be available to run with this command.
|
|
|
|
For example, if you define and install the following extension:
|
|
|
|
```python
|
|
from django_components import ComponentCommand, ComponentExtension
|
|
|
|
class HelloCommand(ComponentCommand):
|
|
name = "hello"
|
|
help = "Say hello"
|
|
def handle(self, *args, **kwargs):
|
|
print("Hello, world!")
|
|
|
|
class MyExt(ComponentExtension):
|
|
name = "my_ext"
|
|
commands = [HelloCommand]
|
|
```
|
|
|
|
You can run the `hello` command with:
|
|
|
|
```bash
|
|
python manage.py components ext run my_ext hello
|
|
```
|
|
|
|
You can also define arguments for the command, which will be passed to the command's `handle` method.
|
|
|
|
```python
|
|
from django_components import CommandArg, ComponentCommand, ComponentExtension
|
|
|
|
class HelloCommand(ComponentCommand):
|
|
name = "hello"
|
|
help = "Say hello"
|
|
arguments = [
|
|
CommandArg(name="name", help="The name to say hello to"),
|
|
CommandArg(name=["--shout", "-s"], action="store_true"),
|
|
]
|
|
|
|
def handle(self, name: str, *args, **kwargs):
|
|
shout = kwargs.get("shout", False)
|
|
msg = f"Hello, {name}!"
|
|
if shout:
|
|
msg = msg.upper()
|
|
print(msg)
|
|
```
|
|
|
|
You can run the command with:
|
|
|
|
```bash
|
|
python manage.py components ext run my_ext hello --name John --shout
|
|
```
|
|
|
|
!!! note
|
|
|
|
Command arguments and options are based on Python's `argparse` module.
|
|
|
|
For more information, see the [argparse documentation](https://docs.python.org/3/library/argparse.html).
|
|
|
|
|
|
## `components list`
|
|
|
|
```txt
|
|
usage: python manage.py components list [-h] [--all] [--columns COLUMNS] [-s]
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/commands/list.py#L89" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
List all components created in this project.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--all`
|
|
- Show all columns. Same as `--columns name,full_name,path`.
|
|
- `--columns COLUMNS`
|
|
- Comma-separated list of columns to show. Available columns: name, full_name, path. Defaults to `--columns full_name,path`.
|
|
- `-s`, `--simple`
|
|
- Only show table data, without headers. Use this option for generating machine-readable output.
|
|
|
|
|
|
|
|
|
|
List all components.
|
|
|
|
```bash
|
|
python manage.py components list
|
|
```
|
|
|
|
Prints the list of available components:
|
|
|
|
```txt
|
|
full_name path
|
|
==================================================================================================
|
|
project.pages.project.ProjectPage ./project/pages/project
|
|
project.components.dashboard.ProjectDashboard ./project/components/dashboard
|
|
project.components.dashboard_action.ProjectDashboardAction ./project/components/dashboard_action
|
|
```
|
|
|
|
To specify which columns to show, use the `--columns` flag:
|
|
|
|
```bash
|
|
python manage.py components list --columns name,full_name,path
|
|
```
|
|
|
|
Which prints:
|
|
|
|
```txt
|
|
name full_name path
|
|
==================================================================================================
|
|
ProjectPage project.pages.project.ProjectPage ./project/pages/project
|
|
ProjectDashboard project.components.dashboard.ProjectDashboard ./project/components/dashboard
|
|
ProjectDashboardAction project.components.dashboard_action.ProjectDashboardAction ./project/components/dashboard_action
|
|
```
|
|
|
|
To print out all columns, use the `--all` flag:
|
|
|
|
```bash
|
|
python manage.py components list --all
|
|
```
|
|
|
|
If you need to omit the title in order to programmatically post-process the output,
|
|
you can use the `--simple` (or `-s`) flag:
|
|
|
|
```bash
|
|
python manage.py components list --simple
|
|
```
|
|
|
|
Which prints just:
|
|
|
|
```txt
|
|
ProjectPage project.pages.project.ProjectPage ./project/pages/project
|
|
ProjectDashboard project.components.dashboard.ProjectDashboard ./project/components/dashboard
|
|
ProjectDashboardAction project.components.dashboard_action.ProjectDashboardAction ./project/components/dashboard_action
|
|
```
|
|
|
|
|
|
## `upgradecomponent`
|
|
|
|
```txt
|
|
usage: upgradecomponent [-h] [--path PATH] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
|
|
[--skip-checks]
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/management/commands/upgradecomponent.py#L89" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Deprecated. Use `components upgrade` instead.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--path PATH`
|
|
- Path to search for components
|
|
- `--version`
|
|
- Show program's version number and exit.
|
|
- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
|
|
- Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
|
|
- `--settings SETTINGS`
|
|
- The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
|
|
- `--pythonpath PYTHONPATH`
|
|
- A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
|
|
- `--traceback`
|
|
- Raise on CommandError exceptions.
|
|
- `--no-color`
|
|
- Don't colorize the command output.
|
|
- `--force-color`
|
|
- Force colorization of the command output.
|
|
- `--skip-checks`
|
|
- Skip system checks.
|
|
|
|
|
|
|
|
|
|
**Deprecated**. Use [`components upgrade`](../commands#components-upgrade) instead.
|
|
|
|
|
|
## `startcomponent`
|
|
|
|
```txt
|
|
usage: startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose] [--dry-run] [--version] [-v {0,1,2,3}]
|
|
[--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks]
|
|
name
|
|
|
|
```
|
|
|
|
|
|
|
|
<a href="https://github.com/django-components/django-components/tree/master/src/django_components/management/commands/startcomponent.py#L89" target="_blank">See source code</a>
|
|
|
|
|
|
|
|
Deprecated. Use `components create` instead.
|
|
|
|
**Positional Arguments:**
|
|
|
|
- `name`
|
|
- The name of the component to create. This is a required argument.
|
|
|
|
**Options:**
|
|
|
|
- `-h`, `--help`
|
|
- show this help message and exit
|
|
- `--path PATH`
|
|
- The path to the component's directory. This is an optional argument. If not provided, the command will use the `COMPONENTS.dirs` setting from your Django settings.
|
|
- `--js JS`
|
|
- The name of the JavaScript file. This is an optional argument. The default value is `script.js`.
|
|
- `--css CSS`
|
|
- The name of the CSS file. This is an optional argument. The default value is `style.css`.
|
|
- `--template TEMPLATE`
|
|
- The name of the template file. This is an optional argument. The default value is `template.html`.
|
|
- `--force`
|
|
- This option allows you to overwrite existing files if they exist. This is an optional argument.
|
|
- `--verbose`
|
|
- This option allows the command to print additional information during component creation. This is an optional argument.
|
|
- `--dry-run`
|
|
- This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is `False`.
|
|
- `--version`
|
|
- Show program's version number and exit.
|
|
- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
|
|
- Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
|
|
- `--settings SETTINGS`
|
|
- The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
|
|
- `--pythonpath PYTHONPATH`
|
|
- A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
|
|
- `--traceback`
|
|
- Raise on CommandError exceptions.
|
|
- `--no-color`
|
|
- Don't colorize the command output.
|
|
- `--force-color`
|
|
- Force colorization of the command output.
|
|
- `--skip-checks`
|
|
- Skip system checks.
|
|
|
|
|
|
|
|
|
|
**Deprecated**. Use [`components create`](../commands#components-create) instead.
|
|
|
|
|