# 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.
Although you can use it like any other live reload tool - with builtin `.gitignore` detection and following, 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)
- [Changelog](#-changelog)
- [Versioning](#-versioning)
- [Licensing](#-licensing)
- [Contribution](#-contribution)
<br>
## ⚡️ Installation
Using [pipx](https://pypa.github.io/pipx/) (recommended):
```
pipx install stellapy
```
On Windows:
```
pip install stellapy
```
On Linux/MacOS:
```
pip3 install 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
follow_symlinks: false
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` and `chrome`.
- **`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.
- **`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`.
* `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`.
* `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
Polling a filesystem for changes can be lengthy in case of big projects.
Even worse when dependencies are vendored within the project, like python virtual environments or include directories in c/c++.
Therefore, you can create a `stella.ignore` file in the project with gitignore-style patterns to exclude certain directories and files to consider.
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 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` only to refresh the browser page.
To stop stella, input `ex`. It will close the browser as well as kill the running process gracefully.
<br>
## 📄 Licensing
License © 2021-Present Shravan Asati
This repository is licensed under the MIT license. See [LICENSE](LICENSE) 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": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"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/24/d5/5b4e0bfaafc3b7d1416b376a27e91fc9e687aa818303e03b1e1e2e61b4b6/stellapy-0.2.1.tar.gz",
"platform": null,
"description": "# stella\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.\nAlthough you can use it like any other live reload tool - with builtin `.gitignore` detection and following, 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- [Changelog](#-changelog)\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\nOn Windows:\n```\npip install stellapy\n```\n\nOn Linux/MacOS:\n```\npip3 install 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\nfollow_symlinks: false\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` and `chrome`.\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.\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 * `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`.\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\nPolling a filesystem for changes can be lengthy in case of big projects.\nEven worse when dependencies are vendored within the project, like python virtual environments or include directories in c/c++.\n\nTherefore, you can create a `stella.ignore` file in the project with gitignore-style patterns to exclude certain directories and files to consider.\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 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` only to refresh the browser page.\n\nTo stop stella, input `ex`. It will close the browser as well as kill the running process gracefully.\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) 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).",
"bugtrack_url": null,
"license": "MIT",
"summary": "Streamline your web dev experience with stella - reload for the terminal as well as browser.",
"version": "0.2.1",
"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": "b088758b7ec32bef04020596f7e23347670a6daf14d54f21814f477f7bb42ee9",
"md5": "d5c331767b0ad2fc6ae5aa72a067dffa",
"sha256": "70155f2580aa4222a1c62ef2388077aae3b85abab8d0ea4572242a088c98ede8"
},
"downloads": -1,
"filename": "stellapy-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5c331767b0ad2fc6ae5aa72a067dffa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 16363,
"upload_time": "2024-02-17T16:00:50",
"upload_time_iso_8601": "2024-02-17T16:00:50.101796Z",
"url": "https://files.pythonhosted.org/packages/b0/88/758b7ec32bef04020596f7e23347670a6daf14d54f21814f477f7bb42ee9/stellapy-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "24d55b4e0bfaafc3b7d1416b376a27e91fc9e687aa818303e03b1e1e2e61b4b6",
"md5": "bff40671edfe147120053461e6883dd7",
"sha256": "471c990c8a1e04962843f29605c5fae23ea5206213fc5b633a7cc98e01b3b2a0"
},
"downloads": -1,
"filename": "stellapy-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "bff40671edfe147120053461e6883dd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 15830,
"upload_time": "2024-02-17T16:00:52",
"upload_time_iso_8601": "2024-02-17T16:00:52.692240Z",
"url": "https://files.pythonhosted.org/packages/24/d5/5b4e0bfaafc3b7d1416b376a27e91fc9e687aa818303e03b1e1e2e61b4b6/stellapy-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-17 16:00:52",
"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
