olog/symconf
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases 1 Wiki Activity

add minor details to usage docs

Browse Source
This commit is contained in:
smgr 2025-09-28 03:43:59 -07:00
parent 4d707b97e4
commit 13e366d1fe
8 changed files with 535 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -6,6 +6,7 @@ __pycache__/
.pytest_cache/ .pytest_cache/
.python-version .python-version
.venv/ .venv/
.ruff_cache/
# vendor and build files # vendor and build files
dist/ dist/

165
README.md
View File

@ -1,63 +1,67 @@
# Symconf # Symconf
`symconf` is a CLI tool for managing local application configuration. It implements a `symconf` is a CLI tool for managing local application configuration. It
general model that supports dynamically switching/reloading themes for any application, implements a general model that supports dynamically switching/reloading themes
and provides a basic means of templatizing your config files. for any application, and provides a basic means of templatizing your config
files.
## Simple example ## Simple example
Below is a simple example demonstrating two system-wide theme switches: Below is a simple example demonstrating two system-wide theme switches:
![Simple example](docs/_static/example.gif) ![Simple example](docs/_static/example.gif)
This GIF shows two `symconf` calls, the first of which applies a `gruvbox` dark theme and This GIF shows two `symconf` calls, the first of which applies a `gruvbox` dark
the second a dark [`monobiome`][1] variant. Each call (of the form `symconf config -m dark -s theme and the second a dark [`monobiome`][1] variant. Each call (of the form
style`) indicates a dark mode preference and a particular color palette that should be `symconf config -m dark -s style`) indicates a dark mode preference and a
used when populating config file templates. Specifically, in this example, invoking particular color palette that should be used when populating config file
`symconf` results in the following app-specific config updates: templates. Specifically, in this example, invoking `symconf` results in the
following app-specific config updates:
- **GTK**: reacts to the mode setting and sets `prefer-dark` system-wide, changing general - **GTK**: reacts to the mode setting and sets `prefer-dark` system-wide,
GTK-responsive applications like Nautilus and Firefox (and subsequently websites that changing general GTK-responsive applications like Nautilus and Firefox (and
are responsive to `prefers-color-scheme`) subsequently websites that are responsive to `prefers-color-scheme`)
- **kitty**: theme template is re-generated using the specified palette, and `kitty` - **kitty**: theme template is re-generated using the specified palette, and
processes are sent a message to live-reload the new config file `kitty` processes are sent a message to live-reload the new config file
- **neovim**: a `vim` theme file (along with a statusline theme) is generated from the - **neovim**: a `vim` theme file (along with a statusline theme) is generated
chosen palette, and running instances of `neovim` are sent a message to re-source this from the chosen palette, and running instances of `neovim` are sent a message
theme (via `nvim --remote-send`) to re-source this theme (via `nvim --remote-send`)
- **waybar**: bar styles are updated to match the mode setting - **waybar**: bar styles are updated to match the mode setting
- **sway**: the background color and window borders are dynamically set to base palette - **sway**: the background color and window borders are dynamically set to base
colors, and `swaymsg reload` is called palette colors, and `swaymsg reload` is called
- **fzf**: a palette-dependent theme is re-generated and re-exported - **fzf**: a palette-dependent theme is re-generated and re-exported
- **rofi**: launcher text and highlight colors are set according to the mode and palette, - **rofi**: launcher text and highlight colors are set according to the mode
applying on next invocation and palette, applying on next invocation
This example highlights the generality of `symconf`, and so long as an app's config can be This example highlights the generality of `symconf`, and so long as an app's
reloaded dynamically, you can use a single `symconf` call to apply themes for an arbitrary config can be reloaded dynamically, you can use a single `symconf` call to
number of apps at once. apply themes for an arbitrary number of apps at once.
# Behavior # Behavior
`symconf` uses a simple operational model that symlinks centralized config files to their `symconf` uses a simple operational model that symlinks centralized config
expected locations across the system. This central config directory can then be version files to their expected locations across the system. This central config
controlled, and app config files can be updated in one place. directory can then be version controlled, and app config files can be updated
in one place.
App config files can either be concrete (fully-specified) or templates (to be populated by App config files can either be concrete (fully-specified) or templates (to be
values conditional on style, e.g., a palette). When `symconf` is executed with a populated by values conditional on style, e.g., a palette). When `symconf` is
particular mode preference (dark or light) and a style (any other indicator of thematic executed with a particular mode preference (dark or light) and a style (any
elements, often simply in the form of a palette like `solarized` or `gruvbox`), it other indicator of thematic elements, often simply in the form of a palette
searches for both concrete and template config files that match and symlinks them to like `solarized` or `gruvbox`), it searches for both concrete and template
registered locations. When necessary, `symconf` will also match and execute scripts to config files that match and symlinks them to registered locations. When
reload apps after updating their configuration. necessary, `symconf` will also match and execute scripts to reload apps after
updating their configuration.
You can find more details on how `symconf`'s matching scheme works in You can find more details on how `symconf`'s matching scheme works in
[Matching](docs/reference/matching.md). [Matching](docs/reference/matching.md).
# Configuring # Configuring
Before using, you must first set up your config directory to house your config files and Before using, you must first set up your config directory to house your config
give `symconf` something to act on. See [Configuring](docs/reference/configuring.md) for files and give `symconf` something to act on. See
details. [Configuring](docs/reference/configuring.md) for details.
# Installation # Installation
The recommended way to install `symconf` is via `pipx`, which is particularly well-suited The recommended way to install `symconf` is via `pipx`, which is particularly
for managing Python packages meant to be used as CLI programs. With `uv` on your system, well-suited for managing Python packages meant to be used as CLI programs. With
you can install with `uv` on your system, you can install with
```sh ```sh
uv tool install symconf uv tool install symconf
@ -74,56 +78,60 @@ You can also install via `pip`, or clone and install locally.
# Usage # Usage
- `-h --help`: print help message - `-h --help`: print help message
- `-c --config-dir`: set the location of the `symconf` config directory - `-c --config-dir`: set the location of the `symconf` config directory
- `symconf config` is the subcommand used to match and set available config files for - `symconf config` is the subcommand used to match and set available config
registered applications files for registered applications
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
all registered apps. consider all registered apps.
* `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`, `any`, or * `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`,
`none`. `any`, or `none`.
* `-s --style`: style indicator, often the name of a color palette, capturing thematic * `-s --style`: style indicator, often the name of a color palette, capturing
details in a config file to be matched. `any` or `none` are reserved keywords (see thematic details in a config file to be matched. `any` or `none` are
below). reserved keywords (see below).
* `-T --template-vars`: additional groups to use when populating templates, in the form * `-T --template-vars`: additional groups to use when populating templates,
`<group>=<value>`, where `<group>` is a template group with a folder in the form `<group>=<value>`, where `<group>` is a template group with a
`$CONFIG_HOME/groups/<group>/` and `<value>` should correspond to a TOML file in this folder `$CONFIG_HOME/groups/<group>/` and `<value>` should correspond to a
folder (i.e., `<value>.toml`). TOML file in this folder (i.e., `<value>.toml`).
- `symconf generate` is a subcommand that can be used for batch generation of config - `symconf generate` is a subcommand that can be used for batch generation of
files. It accepts the same arguments as `symconf config`, but rather than selecting the config files. It accepts the same arguments as `symconf config`, but rather
best match to be used for the system setting, all matching templates are generated. than selecting the best match to be used for the system setting, all matching
There is one additional required argument: templates are generated. There is one additional required argument:
* `-o --output-dir`: the directory under which generated config files should be written. * `-o --output-dir`: the directory under which generated config files should
App-specific subdirectories are created to house config files for each provided app. be written. App-specific subdirectories are created to house config files
for each provided app.
- `symconf install`: runs install scripts for matching apps that specify one - `symconf install`: runs install scripts for matching apps that specify one
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
all registered apps. consider all registered apps.
- `symconf update`: runs update scripts for matching apps that specify one - `symconf update`: runs update scripts for matching apps that specify one
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to consider * `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
all registered apps. consider all registered apps.
The keywords `any` and `none` can be used when specifying `--mode`, `--style`, or as a The keywords `any` and `none` can be used when specifying `--mode`, `--style`,
value in `--template-vars` (and we refer to each of these variables as _factors_ that help or as a value in `--template-vars` (and we refer to each of these variables as
determine a config match): _factors_ that help determine a config match):
- `any` will match config files with _any_ value for this factor, preferring config files - `any` will match config files with _any_ value for this factor, preferring
with a value `none`, indicating no dependence on the factor. This is the default value config files with a value `none`, indicating no dependence on the factor.
when a factor is left unspecified. This is the default value when a factor is left unspecified.
- `none` will match `"none"` directly for a given factor (so no special behavior), but - `none` will match `"none"` directly for a given factor (so no special
used to indicate that a config file is independent of the factor. For instance, behavior), but used to indicate that a config file is independent of the
factor. For instance,
```sh ```sh
symconf config -m light -s none symconf config -m light -s none
``` ```
will match config files that capture the notion of a light mode, but do not depend on or will match config files that capture the notion of a light mode, but do not
provide further thematic components such as a color palette. depend on or provide further thematic components such as a color palette.
## Examples ## Examples
- Set a dark mode for all registered apps, matching any available style/palette component: - Set a dark mode for all registered apps, matching any available style/palette
component:
```sh ```sh
symconf config -m dark symconf config -m dark
``` ```
- Set `solarized` theme for `kitty` and match any available mode (light or dark): - Set `solarized` theme for `kitty` and match any available mode (light or
dark):
```sh ```sh
symconf config -s solarized -a kitty symconf config -s solarized -a kitty
@ -133,16 +141,17 @@ determine a config match):
```sh ```sh
symconf config -m dark -s gruvbox -apps="kitty,nvim" symconf config -m dark -s gruvbox -apps="kitty,nvim"
``` ```
- Set a dark `gruvbox` theme for all apps, and attempt to match other template elements: - Set a dark `gruvbox` theme for all apps, and attempt to match other template
elements:
```sh ```sh
symconf config -m dark -s gruvbox -T font=mono window=sharp symconf config -m dark -s gruvbox -T font=mono window=sharp
``` ```
which would attempt to find and load key-value pairs in the files which would attempt to find and load key-value pairs in the files
`$CONFIG_HOME/groups/font/mono.toml` and `$CONFIG_HOME/groups/window/sharp.toml` to be `$CONFIG_HOME/groups/font/mono.toml` and
used as values when filling templatized config files. `$CONFIG_HOME/groups/window/sharp.toml` to be used as values when filling
templatized config files.
[1]: https://github.com/ologio/monobiome [1]: https://github.com/ologio/monobiome

11
docs/index.md
View File

@ -11,10 +11,11 @@
:recursive: :recursive:
symconf.config symconf.config
symconf.template
symconf.matching
symconf.reader symconf.reader
symconf.runner symconf.runner
symconf.matching
symconf.template
symconf.util
``` ```
## Auto-reference contents ## Auto-reference contents
@ -28,10 +29,10 @@ _autoref/symconf.rst
:maxdepth: 2 :maxdepth: 2
:caption: Contents :caption: Contents
reference/configuring
reference/usage
reference/archive reference/archive
reference/documentation/index reference/configuring
reference/matching
reference/usage
``` ```
```{include} ../README.md ```{include} ../README.md

348
docs/reference/archive.md
View File

@ -1,80 +1,89 @@
# Archive # Archive
The `autoconf` project is an attempt at wrangling the complexity of configuring many The `autoconf` project is an attempt at wrangling the complexity of configuring
applications across one's Linux system. It provides a simple operational model for pulling many applications across one's Linux system. It provides a simple operational
many application config files into one place, as well as generating/setting color schemes model for pulling many application config files into one place, as well as
across apps. generating/setting color schemes across apps.
Quick terminology rundown for theme-related items: Quick terminology rundown for theme-related items:
- **Theme**: loose term referring generally to the overall aesthetic of a visual setting. - **Theme**: loose term referring generally to the overall aesthetic of a
Ignoring stylistic changes (only applicable to some apps; example here might be a visual setting. Ignoring stylistic changes (only applicable to some apps;
a particular setting of the `waybar` layout), a theme is often just the wrapper term for example here might be a a particular setting of the `waybar` layout), a theme
a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_ is often just the wrapper term for a choice of color _palette_ and _scheme_.
setting for an app like `kitty`, referring to both a palette and scheme. For example, "tone4-light" could be a _theme_ setting for an app like
- **Palette**: a set of base colors used to style text or other aspects of an app's `kitty`, referring to both a palette and scheme.
displayed assets - **Palette**: a set of base colors used to style text or other aspects of an
app's displayed assets
- **Scheme**: an indication of lightness, typically either "light" or "dark. - **Scheme**: an indication of lightness, typically either "light" or "dark.
As far as managing settings across apps, there are current two useful classifications As far as managing settings across apps, there are current two useful
here: classifications here:
1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme 1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color
components effectively built in to their canonical configuration file. This can make it scheme components effectively built in to their canonical configuration
hard to set themes dynamically, as it would likely require some involved file. This can make it hard to set themes dynamically, as it would likely
matching/substitution rules. This is not a level of complexity I'm willing to embrace, require some involved matching/substitution rules. This is not a level of
so we simply split the config files according to theme and/or scheme. complexity I'm willing to embrace, so we simply split the config files
2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism according to theme and/or scheme.
for loading themes. This typically implies some distinct color format, although usually 2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear
somewhat easy to generate (don't have to navigate non-color settings, for instance). mechanism for loading themes. This typically implies some distinct color
Such apps allow for an even less "invasive" config swapping process when setting a new format, although usually somewhat easy to generate (don't have to navigate
theme, as one can just swap out the external theme file. non-color settings, for instance). Such apps allow for an even less
"invasive" config swapping process when setting a new theme, as one can just
swap out the external theme file.
To be clear on operation implications here: apps of type (1) must have _manually To be clear on operation implications here: apps of type (1) must have
maintained_ config variations according the desired themes. General theme settings must _manually maintained_ config variations according the desired themes. General
follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set theme settings must follow the naming scheme
`sway` to a light variation (which, at the time of writing, would just entail changing a `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set `sway`
single background color), I must have explicitly created a `sway-tone4-light.conf` file to a light variation (which, at the time of writing, would just entail changing
that captures this setting. The canonical config file will then be symlinked to the a single background color), I must have explicitly created a
theme-specific file when the theme is set. (Note that the palette in this example is pretty much `sway-tone4-light.conf` file that captures this setting. The canonical config
irrelevant, but it needs to be present in order to match the overarching setting; here you file will then be symlinked to the theme-specific file when the theme is set.
can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the (Note that the palette in this example is pretty much irrelevant, but it needs
provided theme name.) to be present in order to match the overarching setting; here you can just
think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is
the provided theme name.)
For apps of type (2), the canonical config file can remain untouched so long as it refers For apps of type (2), the canonical config file can remain untouched so long as
to a fixed, generic theme file. For example, with `kitty`, my config file can point to a it refers to a fixed, generic theme file. For example, with `kitty`, my config
`current-theme.conf` file, which will be symlinked to a specific theme file here in file can point to a `current-theme.conf` file, which will be symlinked to a
`autoconf` when a change is requested. This enables a couple of conveniences: specific theme file here in `autoconf` when a change is requested. This enables
a couple of conveniences:
- The true config directory on disk remains unpolluted with theme variants. - The true config directory on disk remains unpolluted with theme variants.
- If the set theme is regenerated, there is no intervention necessary to propagate its - If the set theme is regenerated, there is no intervention necessary to
changes to the target app. The symlinked file itself will be updated when the theme propagate its changes to the target app. The symlinked file itself will be
does, ensuring the latest theme version is always immediately available and pointed to updated when the theme does, ensuring the latest theme version is always
by the app. immediately available and pointed to by the app.
Keep in mind that some apps may fall into some grey area here, allowing some external Keep in mind that some apps may fall into some grey area here, allowing some
customization but locking down other settings internally. In such instances, there's no external customization but locking down other settings internally. In such
need to overcomplicate things; just stick to explicit config variants under the type (1) instances, there's no need to overcomplicate things; just stick to explicit
umbrella. Type (2) only works for generated themes anyhow; even if the target app can load config variants under the type (1) umbrella. Type (2) only works for generated
an external theme, type (1) should be used if preset themes are fixed. themes anyhow; even if the target app can load an external theme, type (1)
should be used if preset themes are fixed.
## Naming standards ## Naming standards
To keep things simple, we use a few fixed naming standards for setting app config files To keep things simple, we use a few fixed naming standards for setting app
and their themed counterparts. The app registry requires each theme-eligible app to config files and their themed counterparts. The app registry requires each
provide a config directory (`config_dir`), containing some canonical config file theme-eligible app to provide a config directory (`config_dir`), containing
(`config_file`) and to serve as a place for theme-specific config variations. The some canonical config file (`config_file`) and to serve as a place for
following naming schemes must be used in order for theme switching to behave theme-specific config variations. The following naming schemes must be used in
appropriately: order for theme switching to behave appropriately:
- When setting a theme for a particular app, the following variables will be available: - When setting a theme for a particular app, the following variables will be
available:
* `<app-name>` * `<app-name>`
* `<palette>` * `<palette>`
* `<scheme>` * `<scheme>`
- For apps with `external_theme = False`, config variants must named as - For apps with `external_theme = False`, config variants must named as
`<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file `<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default
extension. config file extension.
- For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will - For apps with `external_theme = True`, the file
be used when symlinking the requested theme. The config file thus must point to this `<config-dir>/current-theme.conf` will be used when symlinking the requested
file in order to change with the set theme. theme. The config file thus must point to this file in order to change with
the set theme.
Additionally, the theme symlink will be created from the file Additionally, the theme symlink will be created from the file
@ -87,147 +96,162 @@ appropriately:
## Directory structure ## Directory structure
- `autoconf/`: main repo directory - `autoconf/`: main repo directory
* `config/`: app-specific configuration files. Each folder inside this directory is * `config/`: app-specific configuration files. Each folder inside this
app-specific, and the target of associated copy operations when a config sync is directory is app-specific, and the target of associated copy operations
performed. Nothing in this directory should pertain to any repo functionality; it when a config sync is performed. Nothing in this directory should pertain
should only contain config files that originated elsewhere on the system. to any repo functionality; it should only contain config files that
* `themes/`: app-independent theme data files. Each folder in this directory should originated elsewhere on the system.
correspond to a specific color palette and house any relevant color spec files * `themes/`: app-independent theme data files. Each folder in this
(currently likely be a `colors.json`). Also servers the output location for directory should correspond to a specific color palette and house any
generated theme files relevant color spec files (currently likely be a `colors.json`). Also
* `<palette>/colors.json`: JSON formatted color key-value pairings for palette servers the output location for generated theme files
colors. There's no standard here aside from the filename and format; downstream * `<palette>/colors.json`: JSON formatted color key-value pairings for
app-specific TOML templates can be dependent on any key naming scheme within the palette colors. There's no standard here aside from the filename and
JSON. format; downstream app-specific TOML templates can be dependent on
+ `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color any key naming scheme within the JSON.
palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to + `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the
`<fname>.conf` in the theme output folder (below), so ensure the naming color palette `<palette>` under app `<app-name>`. Files
standards align with those outlined above. `<fname>.toml` will be mapped to `<fname>.conf` in the theme output
+ `<palette>/apps/<app-name>/generated/`: output directory for generated scheme folder (below), so ensure the naming standards align with those
variants. These are the symlink targets for dynamically set external themes. outlined above.
* `app_registry.toml`: global application "registry" used by sync and theme-setting + `<palette>/apps/<app-name>/generated/`: output directory for
scripts. This lets apps be dynamically added or removed from being eligible for generated scheme variants. These are the symlink targets for
config-related operations. dynamically set external themes.
* `app_registry.toml`: global application "registry" used by sync and
theme-setting scripts. This lets apps be dynamically added or removed
from being eligible for config-related operations.
## Scripts ## Scripts
`set_theme.py`: sets a theme across select apps. `set_theme.py`: sets a theme across select apps.
- Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with - Applies to specific app with `-a <app>` , or to all apps in the
`-a "*"`. `app_registry.toml` with `-a "*"`.
- Uses symlinks to set canonical config files to theme-based variations. Which files get - Uses symlinks to set canonical config files to theme-based variations. Which
set depends on the _app type_ (see above), which really just boils down to whether files get set depends on the _app type_ (see above), which really just boils
theming (1) can be specified with an external format, and (2) if it depends on down to whether theming (1) can be specified with an external format, and (2)
auto-generated theme files from within `autoconf`. if it depends on auto-generated theme files from within `autoconf`.
- Palette and scheme are specified as expected. They are used to infer proper paths - Palette and scheme are specified as expected. They are used to infer proper
according to naming and structure standards. paths according to naming and structure standards.
- Real config files will never be overwritten. To begin setting themes with the script, - Real config files will never be overwritten. To begin setting themes with the
you must delete the canonical config file expected by the app (and specified in the app script, you must delete the canonical config file expected by the app (and
registry) to allow the first symlink to be set. From there on out, symlinks will be specified in the app registry) to allow the first symlink to be set. From
automatically flushed. there on out, symlinks will be automatically flushed.
- A report will be provided on which apps were successfully set to the requested theme, - A report will be provided on which apps were successfully set to the
along with the file stems. A number of checks are in place for the existence of involved requested theme, along with the file stems. A number of checks are in place
files and directories. Overall, the risk of overwritting a real config file is low; we for the existence of involved files and directories. Overall, the risk of
only flush existing symlinks, and if the would-be target for the requested theme (be it overwritting a real config file is low; we only flush existing symlinks, and
from an auto-generated theme file, or from a manually manage config variant) doesn't if the would-be target for the requested theme (be it from an auto-generated
exist, that app's config will be completed skipped. Essentially, everything must be in theme file, or from a manually manage config variant) doesn't exist, that
app's config will be completed skipped. Essentially, everything must be in
perfect shape before the symlink trigger is officially pulled. perfect shape before the symlink trigger is officially pulled.
`gen_theme.py`: generates theme files for palettes by mapping their color
definitions through app-specific templates. These templates specific how to
relate an app's theme variables to the color names provided by the template.
`gen_theme.py`: generates theme files for palettes by mapping their color definitions - An app and palette are the two required parameters. If no template or output
through app-specific templates. These templates specific how to relate an app's theme paths are provided, they will be inferred according to the theme path
variables to the color names provided by the template. standards seen above.
- The `--template` argument can be a directory or a file, depending on what
theme files you'd like to render.
- The `--output` path, if specified, must be a directory. Generated theme files
take on a name with the same stem as their source template, but using the
`.conf` extension.
- The TOML templates should make config variable names to JSON dot-notation
accessors. If color definitions are nested, the dot notation should be
properly expanded by the script when mapping the colors to keyword values.
- There are a number of checks for existing paths, even those inferred (e.g.,
template and output) from the palette and app. If the appropriate setup
hasn't been followed, the script will fail. Make sure the `theme` folder in
question and it's nested `app` directory are correctly setup before running
the script. (Perhaps down the line there are some easy auto-setup steps to
take here, but I'm not making that jump now.)
- TODO: open up different app "writers," or make it easy to extend output
syntax based on the app in question. This would like be as simple as mapping
app names to line-generating functions, which accept the keyword and color
(among other items). This can be fleshed out as needed.
- An app and palette are the two required parameters. If no template or output paths are `sync.sh`: copies relevant configuration files from local paths into the
provided, they will be inferred according to the theme path standards seen above. `autoconf` subpath. Markdown files in the docs directory then reference the
- The `--template` argument can be a directory or a file, depending on what theme files local copies of these files, meaning the documentation updates dynamically when
you'd like to render. the configuration files do. That is, the (possibly extracted) config snippets
- The `--output` path, if specified, must be a directory. Generated theme files take on will change with the current state of my system config without any manual
a name with the same stem as their source template, but using the `.conf` extension. intervention of the documentation files.
- The TOML templates should make config variable names to JSON dot-notation accessors. If
color definitions are nested, the dot notation should be properly expanded by the script
when mapping the colors to keyword values.
- There are a number of checks for existing paths, even those inferred (e.g., template and
output) from the palette and app. If the appropriate setup hasn't been followed, the
script will fail. Make sure the `theme` folder in question and it's nested `app`
directory are correctly setup before running the script. (Perhaps down the line there
are some easy auto-setup steps to take here, but I'm not making that jump now.)
- TODO: open up different app "writers," or make it easy to extend output syntax based on
the app in question. This would like be as simple as mapping app names to
line-generating functions, which accept the keyword and color (among other items). This
can be fleshed out as needed.
`sync.sh`: copies relevant configuration files from local paths into the `autoconf`
subpath. Markdown files in the docs directory then reference the local copies of these
files, meaning the documentation updates dynamically when the configuration files do. That
is, the (possibly extracted) config snippets will change with the current state of my
system config without any manual intervention of the documentation files.
### Specific theme-setting example ### Specific theme-setting example
To make clear how the theme setting script works on my system, the following breaks down To make clear how the theme setting script works on my system, the following
exactly what steps are taken to exert as much scheme control as possible. Everything at this breaks down exactly what steps are taken to exert as much scheme control as
point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're possible. Everything at this point is wrapped up in a single `make
currently running the dark scheme (see first image) and I run `make set-tone4-light`: set-<palette>-<scheme>` call; suppose we're currently running the dark scheme
(see first image) and I run `make set-tone4-light`:
![ ![
Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
system-dependent default theme set). In Firefox, I have open `localsys` with its system-dependent default theme set). In Firefox, I have open `localsys` with
scheme-mode to set to "auto," which should reflect the theme setting picked up by the its scheme-mode to set to "auto," which should reflect the theme setting
browser (and note the white tab icon). picked up by the browser (and note the white tab icon).
](_static/set-theme-1.png) ](_static/set-theme-1.png)
_(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the _(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
system-dependent default theme set). In Firefox, I have open `localsys` with its system-dependent default theme set). In Firefox, I have open `localsys` with
scheme-mode to set to "auto," which should reflect the theme setting picked up by the its scheme-mode to set to "auto," which should reflect the theme setting picked
browser (and note the white tab icon).)_ up by the browser (and note the white tab icon).)_
1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`), 1. `set_theme.py` is invoked. Global settings are applied first, based on my OS
which calls (`Linux`), which calls
``` ```
gsettings set org.gnome.desktop.interface color-scheme 'prefer-light' gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
``` ```
controlling settings for GTK apps and other `desktop-portal`-aware programs. This controlling settings for GTK apps and other `desktop-portal`-aware programs.
yields the following: This yields the following:
![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png) ![Portal-aware apps changed, config apps not yet set](_static/set-theme-2.png)
_(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated _(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are
without page refresh.)_ updated without page refresh.)_
2. Specific application styles are set. For now the list is small, including `kitty`, 2. Specific application styles are set. For now the list is small, including
`waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other `kitty`, `waybar`, and `sway`. `kitty` is the only type (2) application
two are type (1). here, whereas the other two are type (1).
a. For the type (1) apps, the canonical config files as specified in the app registry a. For the type (1) apps, the canonical config files as specified in the app
are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`, registry are symlinked to their light variants. For `sway`, this is
and if we look at the `file`: `~/.config/sway/config`, and if we look at the `file`:
```sh ```sh
.config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light .config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
``` ```
b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the b. For the type (2) apps, just the `current-theme.conf` file is symlinked to
relevant palette-scheme file. `kitty` is such an app, with a supported theme file the relevant palette-scheme file. `kitty` is such an app, with a
for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at supported theme file for `tone4`, and those files have been
this file under the `kitty` config directory: auto-generated via `gen_theme.py`. Looking at this file under the `kitty`
config directory:
```sh ```sh
.config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf .config/kitty/current-theme.conf: symbolic link to
~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
``` ```
The `kitty.conf` file isn't changed, as all palette-related items are specified in The `kitty.conf` file isn't changed, as all palette-related items are
the theme file. (Note that the general notion of a "theme" could include changes to specified in the theme file. (Note that the general notion of a "theme"
other stylistic aspects, like the font family; this would likely require some hybrid could include changes to other stylistic aspects, like the font family;
type 1-2 approach not yet implemented). this would likely require some hybrid type 1-2 approach not yet
3. Live application instances are reloaded, according to the registered `refresh_cmd`s. implemented).
Here the apps with style/config files set in step (2) are reloaded to reflect those 3. Live application instances are reloaded, according to the registered
changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`. `refresh_cmd`s. Here the apps with style/config files set in step (2) are
reloaded to reflect those changes. Again, in this example, this is `kitty`,
`sway`, and the `waybar`.
![Final light setting: portal-dependent apps _and_ config-based apps changed](_static/set-theme-3.png) ![
Final light setting: portal-dependent apps _and_ config-based apps changed
](_static/set-theme-3.png)
_(Final light setting: portal-dependent apps _and_ config-based apps changed)_ _(Final light setting: portal-dependent apps _and_ config-based apps
4. `set_theme.py` provides a report for the actions taken; in this case, the following was changed)_
printed: 4. `set_theme.py` provides a report for the actions taken; in this case, the
following was printed:
![`set_theme.py` output](_static/set-theme-4.png) ![`set_theme.py` output](_static/set-theme-4.png)
_(`set_theme.py` output)_ _(`set_theme.py` output)_

169
docs/reference/configuring.md
View File

@ -1,61 +1,64 @@
# Configuring # Configuring
`symconf` operates on a central directory that houses all of the config files you may wish `symconf` operates on a central directory that houses all of the config files
to apply. The default location for this directory is your `$XDG_CONFIG_HOME` (e.g., you may wish to apply. The default location for this directory is your
`~/.config/symconf/`), but it can be any location on your system so long as it's specified `$XDG_CONFIG_HOME` (e.g., `~/.config/symconf/`), but it can be any location on
(see more in Usage). your system so long as it's specified (see more in Usage).
`symconf` expects you to create two top-level components in your config directory: an `symconf` expects you to create two top-level components in your config
`apps/` directory and an `app_registry.toml` file. directory: an `apps/` directory and an `app_registry.toml` file.
**High-level view**: **High-level view**:
- `symconf` operates on a single directory that houses all your config files - `symconf` operates on a single directory that houses all your config files
- Config files in this directory must be placed under an `apps/<app-name>/` folder to be - Config files in this directory must be placed under an `apps/<app-name>/`
associated with the app `<app-name>` folder to be associated with the app `<app-name>`
- For apps to be visible, you need an `app_registry.toml` file that tells `symconf` where - For apps to be visible, you need an `app_registry.toml` file that tells
to symlink your files in `apps/` `symconf` where to symlink your files in `apps/`
## Apps directory ## Apps directory
An `apps/` directory should be created in your config home, with a subdirectory An `apps/` directory should be created in your config home, with a subdirectory
`apps/<app-name>/` for each app with config files that you'd like to be visible to `apps/<app-name>/` for each app with config files that you'd like to be visible
`symconf`. Note that simply populating an app's config folder here will do nothing on its to `symconf`. Note that simply populating an app's config folder here will do
own; the app must also have been registered (discussed in item #2) in order for these nothing on its own; the app must also have been registered (discussed in item
files to be used when `symconf` is invoked. (This just means you can populate your `apps/` #2) in order for these files to be used when `symconf` is invoked. (This just
folder safely without expecting any default behavior. More often than not you'll be means you can populate your `apps/` folder safely without expecting any default
expected to tell `symconf` exactly where your config files should end up, meaning you know behavior. More often than not you'll be expected to tell `symconf` exactly
exactly what it's doing.) where your config files should end up, meaning you know exactly what it's
doing.)
### User config ### User config
Inside your app-specific subdirectory, your managed config files should be placed in a Inside your app-specific subdirectory, your managed config files should be
`user/` subdirectory (distinguishing them from those generated by templates; see more placed in a `user/` subdirectory (distinguishing them from those generated by
in Themes). Your config files themselves are then expected to follow a specific naming templates; see more in Themes). Your config files themselves are then expected
scheme: to follow a specific naming scheme:
```sh ```sh
<palette>-<scheme>.<config-name> <palette>-<scheme>.<config-name>
``` ```
This ties your config file to a particular theme setting as needed, and `symconf` will This ties your config file to a particular theme setting as needed, and
apply it if it matches the theme setting you provide when invoked. The specific values are `symconf` will apply it if it matches the theme setting you provide when
as follows: invoked. The specific values are as follows:
- `scheme`: can be `light`, `dark`, or `none`. Indicates whether the config file should - `scheme`: can be `light`, `dark`, or `none`. Indicates whether the config
be applied specifically when requesting a light or dark mode. Use `none` to indicate file should be applied specifically when requesting a light or dark mode. Use
that the config file does not have settings specific to a light/dark mode. `none` to indicate that the config file does not have settings specific to a
- `palette`: a "palette name" of your choosing, or `none`. The palette name you use light/dark mode.
here may refer specifically to a color palette used by the config file, but can be - `palette`: a "palette name" of your choosing, or `none`. The palette name you
used generally to indicate any particular group of config settings (e.g., fonts, use here may refer specifically to a color palette used by the config file,
transparency, etc). Use `none` to indicate that the file does not correspond to any but can be used generally to indicate any particular group of config settings
particular style group. (e.g., fonts, transparency, etc). Use `none` to indicate that the file does
- `config-name`: the _name_ of the config file. This should correspond to _same path not correspond to any particular style group.
name_ that is expected by the app being configured. For example, if your app expects a - `config-name`: the _name_ of the config file. This should correspond to _same
config file at `a/b/c/d.conf`, "`d.conf`" is the path name. path name_ that is expected by the app being configured. For example, if your
app expects a config file at `a/b/c/d.conf`, "`d.conf`" is the path name.
When invoking `symconf` with specific scheme and palette settings (see more in Usage), When invoking `symconf` with specific scheme and palette settings (see more in
appropriate config files can be matched based on how you've named your files. Usage), appropriate config files can be matched based on how you've named your
files.
For example, suppose I want to set up a simple light/dark mode switch for the `kitty` For example, suppose I want to set up a simple light/dark mode switch for the
terminal emulator. The following tree demonstrates a valid setup: `kitty` terminal emulator. The following tree demonstrates a valid setup:
```sh ```sh
<config-home> <config-home>
@ -66,30 +69,31 @@ terminal emulator. The following tree demonstrates a valid setup:
└── none-dark.kitty.conf └── none-dark.kitty.conf
``` ```
where `none-light.kitty.conf` may set a light background and `none-dark.kitty.conf` a dark where `none-light.kitty.conf` may set a light background and
one. `none` is used for the `<palette>` part of the name to indicate the configuration does `none-dark.kitty.conf` a dark one. `none` is used for the `<palette>` part of
not pertain to any specific palette and can be matched even if one is not provided. With the name to indicate the configuration does not pertain to any specific palette
an appropriate `app_regsitry.toml` file (see below), invoking and can be matched even if one is not provided. With an appropriate
`app_regsitry.toml` file (see below), invoking
```sh ```sh
symconf --theme=light --apps=kitty symconf --theme=light --apps=kitty
``` ```
would symlink `$XDG_CONFIG_HOME/symconf/apps/kitty/user/none-light.kitty.conf` to would symlink `$XDG_CONFIG_HOME/symconf/apps/kitty/user/none-light.kitty.conf`
`~/.config/kitty/kitty.conf`. to `~/.config/kitty/kitty.conf`.
### Templatized config ### Templatized config
Note the potential inconvenience in needing to manage two separate config files in the Note the potential inconvenience in needing to manage two separate config files
above example, very likely with all but one line of difference. Templating enables in the above example, very likely with all but one line of difference.
populating config template files dynamically with theme-specific variables of your Templating enables populating config template files dynamically with
choosing. theme-specific variables of your choosing.
### Reload scripts ### Reload scripts
After symlinking a new set of config files, it is often necessary to reload the system or After symlinking a new set of config files, it is often necessary to reload the
relevant apps in order for the new config settings to apply. Within an app's subdirectory, system or relevant apps in order for the new config settings to apply. Within
a `call/` folder can be created to hold scripts that should apply based on certain schemes an app's subdirectory, a `call/` folder can be created to hold scripts that
or palettes (matching them in the same way as config files). For example, should apply based on certain schemes or palettes (matching them in the same
way as config files). For example,
```sh ```sh
<config-home> <config-home>
@ -99,22 +103,22 @@ or palettes (matching them in the same way as config files). For example,
└── none-none.sh └── none-none.sh
``` ```
`none-none.sh` might simply contain `kill -s USR1 $(pgrep kitty)`, which is a way to tell `none-none.sh` might simply contain `kill -s USR1 $(pgrep kitty)`, which is a
all running `kitty` instances to reload their config settings. Again, following the naming way to tell all running `kitty` instances to reload their config settings.
scheme for config files, a script named `none-none.sh` will apply under any scheme or Again, following the naming scheme for config files, a script named
palette specification. Thus, in our light/dark mode switch example, invoking `symconf `none-none.sh` will apply under any scheme or palette specification. Thus, in
--theme=light --apps=kitty` would: our light/dark mode switch example, invoking `symconf --theme=light
--apps=kitty` would:
1. Search and match the config name `none-light.kitty.conf` and symlink it to 1. Search and match the config name `none-light.kitty.conf` and symlink it to
`~/.config/kitty/kitty.conf`. `~/.config/kitty/kitty.conf`.
2. Search and match `none-none.sh` and execute it, applying the new light mode settings to 2. Search and match `none-none.sh` and execute it, applying the new light mode
all running `kitty` instances. settings to all running `kitty` instances.
## App registry ## App registry
An `app_registry.toml` file, used to specify the target locations for app-specific An `app_registry.toml` file, used to specify the target locations for
config files. To "register" an app, you simply need to add the following text block to app-specific config files. To "register" an app, you simply need to add the
the `app_registry.toml` file: following text block to the `app_registry.toml` file:
```toml ```toml
[app.<app-name>] [app.<app-name>]
@ -128,22 +132,22 @@ config_map = {
} }
``` ```
(Note that text in angle brackets refers to values that should be replaced.) This tells (Note that text in angle brackets refers to values that should be replaced.)
`symconf` how it should handle each app's config files. The `<app-name>` (e.g., This tells `symconf` how it should handle each app's config files. The
`kitty`) should correspond to a subdirectory under `apps/` (e.g., `apps/kitty/`) that `<app-name>` (e.g., `kitty`) should correspond to a subdirectory under `apps/`
holds your config files for that app. As shown, you then need to supply either of the (e.g., `apps/kitty/`) that holds your config files for that app. As shown, you
following options: then need to supply either of the following options:
- `config_dir`: specifies a single directory where all of the app's matching config - `config_dir`: specifies a single directory where all of the app's matching
files should be symlinked. In the `kitty` example, this might be `~/.config/kitty`. config files should be symlinked. In the `kitty` example, this might be
This is the simplest and most common option provided most apps expect all of their `~/.config/kitty`. This is the simplest and most common option provided most
config files to be in a single directory. apps expect all of their config files to be in a single directory.
- `config_map`: a dictionary mapping config file _path names_ to the _exact paths_ that - `config_map`: a dictionary mapping config file _path names_ to the _exact
should be created during the symlink process. This is typically needed when an app paths_ that should be created during the symlink process. This is typically
has many config files that need to be set in several disparate locations across your needed when an app has many config files that need to be set in several
system. In the `kitty` example, although not necessary (and in general you should disparate locations across your system. In the `kitty` example, although not
prefer to set `config_dir` when applicable), we could have the following necessary (and in general you should prefer to set `config_dir` when
`config_map`: applicable), we could have the following `config_map`:
```toml ```toml
[app.kitty] [app.kitty]
@ -152,8 +156,9 @@ following options:
} }
``` ```
This tells `symconf` to symlink the exact location `~/.config/kitty/kitty.conf` to This tells `symconf` to symlink the exact location
the matching `kitty.conf` under the `apps/kitty` directory. `~/.config/kitty/kitty.conf` to the matching `kitty.conf` under the
`apps/kitty` directory.
## Directory structure ## Directory structure
In total, the structure of your base config directory can look as follows: In total, the structure of your base config directory can look as follows:

168
docs/reference/usage.md
View File

@ -1,6 +1,170 @@
# Usage # Usage
```{toctree} ```sh
:hidden: usage: symconf [-h] [-c CONFIG_DIR] [-v] {config,generate,install,update} ...
Manage application configuration with symlinks.
options:
-h, --help show this help message and exit
-c CONFIG_DIR, --config-dir CONFIG_DIR
Path to config directory
-v, --version Print symconf version
subcommand actions:
{config,generate,install,update}
``` ```
Additional argument details:
- `-h --help`: print help message
- `-c --config-dir`: the location of the `symconf` config directory. Assumes
`$XDG_CONFIG_HOME` (e.g., `~/.config/symconf/`) by default.
## `config` subcommand
The config subcommand applies symlinks for registered application routes that
meet specified constraints.
```sh
usage: symconf config [-h] [-s STYLE] [-m MODE] [-a APPS] [-T TEMPLATE_VARS [TEMPLATE_VARS ...]]
Set config files for registered applications.
options:
-h, --help show this help message and exit
-s STYLE, --style STYLE
Style indicator (often a color palette) capturing thematic details in a config file
-m MODE, --mode MODE Preferred lightness mode/scheme, either "light," "dark," "any," or "none."
-a APPS, --apps APPS Application target for theme. App must be present in the registry. Use "*" to apply to all registered apps
-T TEMPLATE_VARS [TEMPLATE_VARS ...], --template-vars TEMPLATE_VARS [TEMPLATE_VARS ...]
Groups to use when populating templates, in the form group=value
```
- `symconf config` is the subcommand used to match and set available config
files for registered applications
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
consider all registered apps.
* `-m --mode`: preferred lightness mode/scheme, either `light`, `dark`,
`any`, or `none`.
* `-s --style`: style indicator, often the name of a color palette, capturing
thematic details in a config file to be matched. `any` or `none` are
reserved keywords (see below).
* `-T --template-vars`: additional groups to use when populating templates,
in the form `<group>=<value>`, where `<group>` is a template group with a
folder `$CONFIG_HOME/groups/<group>/` and `<value>` should correspond to a
TOML file in this folder (i.e., `<value>.toml`).
## `generate` subcommand
The generate subcommand fills in templates with theme values matched under
provided constraints,
```sh
usage: symconf generate [-h] -o OUTPUT_DIR [-s STYLE] [-m MODE] [-a APPS] [-T TEMPLATE_VARS [TEMPLATE_VARS ...]]
Generate all template config files for specified apps
options:
-h, --help show this help message and exit
-o OUTPUT_DIR, --output-dir OUTPUT_DIR
Path to write generated template files
-s STYLE, --style STYLE
Style indicator (often a color palette) capturing thematic details in a config file
-m MODE, --mode MODE Preferred lightness mode/scheme, either "light," "dark," "any," or "none."
-a APPS, --apps APPS Application target for theme. App must be present in the registry. Use "*" to apply to all registered apps
-T TEMPLATE_VARS [TEMPLATE_VARS ...], --template-vars TEMPLATE_VARS [TEMPLATE_VARS ...]
Groups to use when populating templates, in the form group=value
```
- `symconf generate` is a subcommand that can be used for batch generation of
config files. It accepts the same arguments as `symconf config`, but rather
than selecting the best match to be used for the system setting, all matching
templates are generated. There is one additional required argument:
* `-o --output-dir`: the directory under which generated config files should
be written. App-specific subdirectories are created to house config files
for each provided app.
## `install` subcommand
The install subcommand runs the `install.sh` scripts for registered apps.
```sh
usage: symconf install [-h] [-a APPS]
Run install scripts for registered applications.
options:
-h, --help show this help message and exit
-a APPS, --apps APPS Application target for theme. App must be present in the registry. Use "*" to apply to all registered apps
```
- `symconf install`: runs install scripts for matching apps
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
consider all registered apps.
## `update` subcommand
The update subcommand runs the `update.sh` scripts for registered apps. This
action expects the install process for each matched app to have been run
beforehand.
```sh
usage: symconf update [-h] [-a APPS]
Run update scripts for registered applications.
options:
-h, --help show this help message and exit
-a APPS, --apps APPS Application target for theme. App must be present in the registry. Use "*" to apply to all registered apps
```
- `symconf update`: runs update scripts for matching apps that specify one
* `-a --apps`: comma-separate list of registered apps, or `"*"` (default) to
consider all registered apps.
## Matching factors
The keywords `any` and `none` can be used when specifying `--mode`, `--style`,
or as a value in `--template-vars` (and we refer to each of these variables as
_factors_ that help determine a config match):
- `any` will match config files with _any_ value for this factor, preferring
config files with a value `none`, indicating no dependence on the factor.
This is the default value when a factor is left unspecified.
- `none` will match `"none"` directly for a given factor (so no special
behavior), but used to indicate that a config file is independent of the
factor. For instance,
```sh
symconf config -m light -s none
```
will match config files that capture the notion of a light mode, but do not
depend on or provide further thematic components such as a color palette.
## Examples
- Set a dark mode for all registered apps, matching any available style/palette
component:
```sh
symconf config -m dark
```
- Set `solarized` theme for `kitty` and match any available mode (light or
dark):
```sh
symconf config -s solarized -a kitty
```
- Set a dark `gruvbox` theme for multiple apps (but not all):
```sh
symconf config -m dark -s gruvbox -apps="kitty,nvim"
```
- Set a dark `gruvbox` theme for all apps, and attempt to match other template
elements:
```sh
symconf config -m dark -s gruvbox -T font=mono window=sharp
```
which would attempt to find and load key-value pairs in the files
`$CONFIG_HOME/groups/font/mono.toml` and
`$CONFIG_HOME/groups/window/sharp.toml` to be used as values when filling
templatized config files.

2
pyproject.toml
View File

@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project] [project]
name = "symconf" name = "symconf"
version = "0.8.2" version = "0.8.3"
description = "Local app configuration manager" description = "Local app configuration manager"
requires-python = ">=3.12" requires-python = ">=3.12"
authors = [ authors = [

2
uv.lock generated
View File

@ -529,7 +529,7 @@ wheels = [
[[package]] [[package]]
name = "symconf" name = "symconf"
version = "0.8.2" version = "0.8.3"
source = { editable = "." } source = { editable = "." }
dependencies = [ dependencies = [
{ name = "colorama" }, { name = "colorama" },