# stella
[](https://pepy.tech/project/stellapy)
stella is a command line utility made for streamlining web development experience.
It is able to reload server as well as the browser page on every file change.
You can use it like any other file watcher too - with builtin `.gitignore` detection and obedience, along with several other features like multiple command execution, and the npm-scripts like interface.
<br>
## 📝 Table of Contents
- [Installation](#%EF%B8%8F-installation)
- [Motivation](#-motivation)
- [How does stella work?](#%EF%B8%8F-how-does-stella-work)
- [Usage](#-usage)
- [Versioning](#-versioning)
- [Licensing](#-licensing)
- [Contribution](#-contribution)
<br>
## ⚡️ Installation
Using [pipx](https://pypa.github.io/pipx/) (recommended):
```
pipx install stellapy
```
To upgrade:
```
pipx upgrade stellapy
```
On Windows:
```
pip install -U stellapy
```
On Linux/MacOS:
```
pip3 install -U stellapy
```
<br>
## 💫 Motivation
I wanted a CLI that could live reload the browser page as well as live restart the server. I tried to find such a tool, but didn't find one. So I made stella - that could reload backend as well as frontend code. Also the builtin "debug modes" of web frameworks sucked.
<br>
## ⚙️ How does stella work?
stella continuously watches for file changes in the project, while respecting the gitignore file and whenever a change is made, it kills the existing process and spawns a new process using subprocess. What about browser reload? It uses selenium to accomplish that.
<br>
## 💡 Usage
This section briefly describes how to use the stella CLI.
### init
```
stella init
```
The `init` command writes a default `stella.yml` config file in the working directory. The default configuration looks like this:
```yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/shravanasati/stellapy/master/schema.json
browser: firefox
include_only: []
poll_interval: 500
browser_wait_interval: 1000
scripts:
- name: default
url: ''
command: echo 'hello'
shell: true
```
This yaml file comes with a schema which can be utilized by yaml language servers to provide autocompletion and validation to make sure the config is correct.
### Configuration
Let's quickly go over the config options:
- **`browser`**: This option specifies the browser to use when `url` is given. The only valid options for browser currently are `firefox`, `chrome`, `edge` and `safari`.
- **`include_only`**: The list of gitignore-style patterns to consider for live reload. This will be used along with the ignore file (`stella.ignore` or `.gitignore`) to match files. eg. `include_only: ["*.py", "*.env"]`.
- **`poll_interval`**: The duration in **milliseconds** to poll the filesystem for changes. This has been modified past v0.3.0 - it now signifies the threshold duration for which stella should accept changes.
- **`browser_wait_interval`**: This is the duration in **milliseconds** between the execution of given command on the terminal and browser page refresh. This can be used in situations when the server takes some time before it is ready to listen on a given port.
<!-- - **`follow_symlinks`**: Boolean value that indicates whether to follow symbolic links encountered in the filesystem. -->
- **`scripts`**: This the list of npm style scripts that take 4 parameters each.
* `name`: Name of the script. To execute a certain script, use its name in the `stella run SCRIPT_NAME` command. The script named _default_ will be used in case SCRIPT_NAME is not provided. Note that this parameter is **case-insensitive**, for convenience.
* `url`: The URL to listen to on the browser. Set it to an empty string (`''`) if you don't want live reload on the browser. eg. `localhost:8000`.
> Note: For chrome and edge, URLs starting with `localhost` won't work, prepend the `url` with a scheme like `http://` or `file://`. Not tested on safari, but if you see `data;` in the address bar, this URL change should fix it.
* `command`: A single command or a list of commands to execute on the terminal. eg.
```
command: python3 app.py
```
```
command:
- go fmt ./...
- go build
- ./main.exe
```
If a list of commands are provided, the `shell` will be considered `true` even if it's `false`, and these commands will be executed **sequentially** one after the other.
* `shell`: **Boolean** value which indicates whether to execute commands inside a shell context (like bash, powershell, zsh...) or as an independent process. This is useful if you want to execute shell scripts directly without invoking the shell interpreter. On Windows, powershell is used as shell (instead of cmd). On Linux and MacOS, the shell used is determined by `SHELL` environment variable. If it's not present, `/bin/sh` will be used.
### Ignore
You can create a `stella.ignore` file in the project with gitignore-style patterns to exclude certain directories and files to watch.
Otherwise, `.gitignore` also just works, and is the recommended way.
However, `stella.ignore` will be the first one that will be searched for. If it's not found, stella will resort to `.gitignore`.
Ignore patterns are cached once stella is started, similar to the stella configuration. If you change either of them, in order to see the desired changes, you need to either type `rc` and press enter or stop stella and run it again.
### run
```
stella run SCRIPT_NAME
stella run SCRIPT_NAME --config-file /path/to/config/stella.yml
```
The `run` command is used to start stella.
It expects one optional argument: the script name (case-insensitive) to run from the config file.
An optional `--config-file` (`-c` for short) flag can be used to specify the config file to be used.
Alternatively, an environment variable named `STELLA_CONFIG` can be set for the same.
If not provided, stella will attempt to find `stella.yml` in the current directory or its parent folders until its found.
While stella is running, you can input `rs` to restart the server and refresh the browser page manually, and `rb` to refresh the browser page.
Since *v0.3.0*, you can also reload the stella configuration by typing `rc` and pressing enter. This will close the existing browser window and the running process, and restart the same script with the stella configuration.
To stop stella, input `ex`. It will close the browser as well as kill the running process gracefully (it sends `SIGTERM` on Unix based systems and `CTRL_BREAK_EVENT` on Windows).
If an error is encountered on refreshing the browser page (an event which can happen often, primarily due to server taking a long time to restart or the command failed to execute successfully), stella will retry with the exponential backoff strategy (2^n) until the browser refresh is successfull or a new change is detected.
<br>
## 📄 Licensing
License © 2021-Present Shravan Asati
This repository is licensed under the MIT license. See [LICENSE](LICENSE.txt) for details.
<br>
## 👥 Contribution
Contribution is more than welcome. For more guidelines on contributing to stella, refer [CONTRIBUTING.md](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/shravanasati/stellapy",
"name": "stellapy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "web dev, development, website, python, cli, stella, reloader, walker, executor, helium, selenium, automation",
"author": "Shravan Asati",
"author_email": "dev.shravan@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/81/60/959ffc49f028ae2e4bd2327ba1cc5d4d4a4bd3aab71bdaf052d6fdb35271/stellapy-0.4.0.tar.gz",
"platform": null,
"description": "# stella\n\n\n\n\n\n[](https://pepy.tech/project/stellapy)\n\nstella is a command line utility made for streamlining web development experience. \nIt is able to reload server as well as the browser page on every file change.\nYou can use it like any other file watcher too - with builtin `.gitignore` detection and obedience, along with several other features like multiple command execution, and the npm-scripts like interface.\n\n<br>\n\n\n## \ud83d\udcdd Table of Contents\n- [Installation](#%EF%B8%8F-installation)\n- [Motivation](#-motivation)\n- [How does stella work?](#%EF%B8%8F-how-does-stella-work)\n- [Usage](#-usage)\n- [Versioning](#-versioning)\n- [Licensing](#-licensing)\n- [Contribution](#-contribution)\n\n\n<br>\n\n\n## \u26a1\ufe0f Installation\n\nUsing [pipx](https://pypa.github.io/pipx/) (recommended):\n```\npipx install stellapy\n```\n\nTo upgrade:\n```\npipx upgrade stellapy \n```\n\nOn Windows:\n```\npip install -U stellapy\n```\n\nOn Linux/MacOS:\n```\npip3 install -U stellapy\n```\n\n\n<br>\n\n\n\n## \ud83d\udcab Motivation\n\nI wanted a CLI that could live reload the browser page as well as live restart the server. I tried to find such a tool, but didn't find one. So I made stella - that could reload backend as well as frontend code. Also the builtin \"debug modes\" of web frameworks sucked.\n\n<br>\n\n## \u2699\ufe0f How does stella work?\n\nstella continuously watches for file changes in the project, while respecting the gitignore file and whenever a change is made, it kills the existing process and spawns a new process using subprocess. What about browser reload? It uses selenium to accomplish that.\n\n<br>\n\n\n## \ud83d\udca1 Usage\n\nThis section briefly describes how to use the stella CLI.\n\n### init\n\n```\nstella init\n```\n\nThe `init` command writes a default `stella.yml` config file in the working directory. The default configuration looks like this:\n\n```yml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/shravanasati/stellapy/master/schema.json \nbrowser: firefox\ninclude_only: []\npoll_interval: 500\nbrowser_wait_interval: 1000\nscripts:\n- name: default\n url: ''\n command: echo 'hello'\n shell: true\n```\n\nThis yaml file comes with a schema which can be utilized by yaml language servers to provide autocompletion and validation to make sure the config is correct.\n\n### Configuration\n\nLet's quickly go over the config options:\n\n - **`browser`**: This option specifies the browser to use when `url` is given. The only valid options for browser currently are `firefox`, `chrome`, `edge` and `safari`.\n\n - **`include_only`**: The list of gitignore-style patterns to consider for live reload. This will be used along with the ignore file (`stella.ignore` or `.gitignore`) to match files. eg. `include_only: [\"*.py\", \"*.env\"]`.\n\n - **`poll_interval`**: The duration in **milliseconds** to poll the filesystem for changes. This has been modified past v0.3.0 - it now signifies the threshold duration for which stella should accept changes.\n\n - **`browser_wait_interval`**: This is the duration in **milliseconds** between the execution of given command on the terminal and browser page refresh. This can be used in situations when the server takes some time before it is ready to listen on a given port.\n\n <!-- - **`follow_symlinks`**: Boolean value that indicates whether to follow symbolic links encountered in the filesystem. -->\n\n - **`scripts`**: This the list of npm style scripts that take 4 parameters each.\n\n * `name`: Name of the script. To execute a certain script, use its name in the `stella run SCRIPT_NAME` command. The script named _default_ will be used in case SCRIPT_NAME is not provided. Note that this parameter is **case-insensitive**, for convenience.\n\n * `url`: The URL to listen to on the browser. Set it to an empty string (`''`) if you don't want live reload on the browser. eg. `localhost:8000`.\n\n > Note: For chrome and edge, URLs starting with `localhost` won't work, prepend the `url` with a scheme like `http://` or `file://`. Not tested on safari, but if you see `data;` in the address bar, this URL change should fix it.\n\n * `command`: A single command or a list of commands to execute on the terminal. eg.\n ```\n command: python3 app.py\n ```\n\n ```\n command: \n - go fmt ./...\n - go build\n - ./main.exe\n ```\n If a list of commands are provided, the `shell` will be considered `true` even if it's `false`, and these commands will be executed **sequentially** one after the other.\n\n * `shell`: **Boolean** value which indicates whether to execute commands inside a shell context (like bash, powershell, zsh...) or as an independent process. This is useful if you want to execute shell scripts directly without invoking the shell interpreter. On Windows, powershell is used as shell (instead of cmd). On Linux and MacOS, the shell used is determined by `SHELL` environment variable. If it's not present, `/bin/sh` will be used.\n\n\n### Ignore\n\nYou can create a `stella.ignore` file in the project with gitignore-style patterns to exclude certain directories and files to watch.\n\nOtherwise, `.gitignore` also just works, and is the recommended way.\n\nHowever, `stella.ignore` will be the first one that will be searched for. If it's not found, stella will resort to `.gitignore`.\n\nIgnore patterns are cached once stella is started, similar to the stella configuration. If you change either of them, in order to see the desired changes, you need to either type `rc` and press enter or stop stella and run it again.\n\n\n### run\n\n```\nstella run SCRIPT_NAME\nstella run SCRIPT_NAME --config-file /path/to/config/stella.yml\n```\n\nThe `run` command is used to start stella.\nIt expects one optional argument: the script name (case-insensitive) to run from the config file.\n\nAn optional `--config-file` (`-c` for short) flag can be used to specify the config file to be used. \nAlternatively, an environment variable named `STELLA_CONFIG` can be set for the same.\n\nIf not provided, stella will attempt to find `stella.yml` in the current directory or its parent folders until its found.\n\n\nWhile stella is running, you can input `rs` to restart the server and refresh the browser page manually, and `rb` to refresh the browser page.\n\nSince *v0.3.0*, you can also reload the stella configuration by typing `rc` and pressing enter. This will close the existing browser window and the running process, and restart the same script with the stella configuration.\n\nTo stop stella, input `ex`. It will close the browser as well as kill the running process gracefully (it sends `SIGTERM` on Unix based systems and `CTRL_BREAK_EVENT` on Windows).\n\nIf an error is encountered on refreshing the browser page (an event which can happen often, primarily due to server taking a long time to restart or the command failed to execute successfully), stella will retry with the exponential backoff strategy (2^n) until the browser refresh is successfull or a new change is detected.\n\n<br>\n\n\n## \ud83d\udcc4 Licensing\n\nLicense \u00a9 2021-Present Shravan Asati\n\nThis repository is licensed under the MIT license. See [LICENSE](LICENSE.txt) for details.\n\n<br>\n\n## \ud83d\udc65 Contribution\n\nContribution is more than welcome. For more guidelines on contributing to stella, refer [CONTRIBUTING.md](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Streamline your web dev experience with stella - reload for the terminal as well as browser.",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/shravanasati/stellapy#readme",
"Homepage": "https://github.com/shravanasati/stellapy",
"Repository": "https://github.com/shravanasati/stellapy"
},
"split_keywords": [
"web dev",
" development",
" website",
" python",
" cli",
" stella",
" reloader",
" walker",
" executor",
" helium",
" selenium",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c724ba1e374c1308d37e3edf8d846f61fc2e40290812729d2f07c690e6774feb",
"md5": "a336d6e18b276ae035d8ac2a3754eb80",
"sha256": "04935885fc2fdc10a684f93d530281e91af16e1a3ce6e35b98e957788542a931"
},
"downloads": -1,
"filename": "stellapy-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a336d6e18b276ae035d8ac2a3754eb80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 17556,
"upload_time": "2024-07-15T15:11:47",
"upload_time_iso_8601": "2024-07-15T15:11:47.923103Z",
"url": "https://files.pythonhosted.org/packages/c7/24/ba1e374c1308d37e3edf8d846f61fc2e40290812729d2f07c690e6774feb/stellapy-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8160959ffc49f028ae2e4bd2327ba1cc5d4d4a4bd3aab71bdaf052d6fdb35271",
"md5": "69db004270bacc8c4d16165947fedc95",
"sha256": "2b4312dc73869d554e95c1b75e4eaf824fcac10b9ca5fd066cecb28ad9bbeb85"
},
"downloads": -1,
"filename": "stellapy-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "69db004270bacc8c4d16165947fedc95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 17470,
"upload_time": "2024-07-15T15:11:49",
"upload_time_iso_8601": "2024-07-15T15:11:49.905356Z",
"url": "https://files.pythonhosted.org/packages/81/60/959ffc49f028ae2e4bd2327ba1cc5d4d4a4bd3aab71bdaf052d6fdb35271/stellapy-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-15 15:11:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shravanasati",
"github_project": "stellapy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stellapy"
}
JSON
