| Name | hachitool JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | Utilities for working with Python scripts in GitHub Actions |
| upload_time | 2024-12-08 22:00:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hachitool
Hachitool is a set of utilities that make it easier to work with Python scripts in GitHub Actions.
## Installation
Hachitool can be installed like any other Python package:
```yaml
- run: pip install hachitool
```
### Inline scripts
Hachitool can be ephemerally installed for inline Python scripts via [uv](https://docs.astral.sh/uv):
```yaml
- uses: astral-sh/setup-uv@v3
- shell: uv run --with hachitool python {0}
run: |
import hachitool
# Do stuff here
```
### External scripts
Hachitool can be emphemerally installed for external scripts via uv and
[inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata):
```python
# script.py
# /// script
# dependencies = [
# "hachitool",
# ]
# ///
import hachitool
# Do stuff here
```
```yaml
# workflow.yml
- uses: astral-sh/setup-uv@v3
- run: uv run script.py
```
## Usage
### `hachitool.set_output`
[Set output parameters for a step](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter).
Takes either:
- a key as its first argument and a value as its second
- a set of key-value pairs as either a dictionary or keyword arguments
```python
import hachitool
# All of these are equivalent
hachitool.set_output("key", "value")
hachitool.set_output({"key": "value"})
hachitool.set_output(key="value")
```
### `hachitool.set_env`
[Set environment variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable).
Takes either:
- a key as its first argument and a value as its second
- a set of key-value pairs as either a dictionary or keyword arguments
```python
import hachitool
# All of these are equivalent
hachitool.set_env("key", "value")
hachitool.set_env({"key": "value"})
hachitool.set_env(key="value")
```
### `hachitool.add_path`
Append something to the system path.
```python
import hachitool
hachitool.add_path("/absolute/or/relative/path")
```
### `hachitool.summary.add`
Add content to
the [step summary](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary).
Supports [GitHub-flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
```python
import hachitool
hachitool.summary.add("this is a summary")
```
> [!TIP]
> Calling `hachitool.summary` directly does the same thing:
> ```python
> import hachitool
>
> hachitool.summary("this is a summary")
> ```
If the keyword-only `overwrite` argument is `True`, existing summary content will be erased:
```python
import hachitool
hachitool.summary.add("this is a summary", overwrite=True)
```
### `hachitool.summary.clear`
Clear the step summary.
```python
import hachitool
hachitool.summary.clear()
```
### `hachitool.mask`
[Mask a value](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log).
```python
import hachitool
hachitool.mask("super secret value")
```
### `hachitool.log`
Print a message to the log. Takes the following arguments:
| **Argument** | **Type** | **Description** | **Required?** |
|--------------|-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|---------------|
| `level` | `"debug"` \| `"notice"` \| `"warning"` \| `"error"` | The log level of the message. | Yes |
| `message` | `str` | The message to print. | Yes |
| `file` | `str` | The path to a file to annotate with the message. | No |
| `line` | `int` \| `tuple[int, int]` | The line(s) of `file` to annotate with the message. A tuple will be interpreted as a pair of starting and ending lines. | No |
| `column` | `int` \| `tuple[int, int]` | The column(s) of `file` to annotate with the message. A tuple will be interpreted as a pair of starting and ending columns. | No | |
`level` and `message` are the first and second positional arguments, respectively.
`file`, `line`, and `column` are keyword-only.
```python
import hachitool
hachitool.log("notice", "this is a notice message", file="main.py", line=1, column=6)
# Using tuples for `line` and `column`
hachitool.log("notice", "this is a notic message", file="main.py", line=(1, 5), column=(6, 10))
```
### `hachitool.debug`, `hachitool.notice`, `hachitool.warning`, `hachitool.error`
Print a `debug`, `notice`, `warning`, or `error` message to the log, respectively. Takes all arguments of
`hachitool.log` except for `level`.
```python
import hachitool
hachitool.debug("this is a debug message")
hachitool.notice("this is a notice message")
hachitool.warning("this is a warning message")
hachitool.error("this is an error message")
```
### `hachitool.fail`
Optionally print an error-level message, then fail the workflow. Takes an optional `exit_code` argument
that must be an integer greater than or equal to 1. Additionally takes all arguments of `hachitool.error`,
except `message` is optional.
```python
import hachitool
hachitool.fail("something went wrong", exit_code=1)
```
### `hachitool.log_group`
Anything printed to the log inside this context manager will be nested inside an
[expandable group](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#grouping-log-lines).
Takes a mandatory `title` argument.
```python
import hachitool
with hachitool.log_group(title="group title"):
print("I'm part of a log group!")
print("me too!")
print("me three!")
```
### `hachitool.literal`
Nothing printed to the log inside this context manager will be interpreted as a workflow command.
```python
import hachitool
hachitool.warning("this is a warning message to show that commands are being processed")
with hachitool.literal():
hachitool.warning("this will not render as a warning because commands are not being processed")
hachitool.warning("this will render as a warning since commands are being processed again")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "hachitool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "celsius narhwal <hello@celsiusnarhwal.dev>",
"download_url": "https://files.pythonhosted.org/packages/4a/5d/0b41a826b8387f4325a6093d6f965fe0c7a1fff0ebd103c67a568d68f6a7/hachitool-1.0.2.tar.gz",
"platform": null,
"description": "# Hachitool\n\nHachitool is a set of utilities that make it easier to work with Python scripts in GitHub Actions.\n\n## Installation\n\nHachitool can be installed like any other Python package:\n\n```yaml\n- run: pip install hachitool\n```\n\n### Inline scripts\n\nHachitool can be ephemerally installed for inline Python scripts via [uv](https://docs.astral.sh/uv):\n\n```yaml\n- uses: astral-sh/setup-uv@v3\n\n- shell: uv run --with hachitool python {0}\n run: |\n import hachitool\n\n # Do stuff here\n```\n\n### External scripts\n\nHachitool can be emphemerally installed for external scripts via uv and\n[inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata):\n\n```python\n# script.py\n\n# /// script\n# dependencies = [\n# \"hachitool\",\n# ]\n# ///\n\nimport hachitool\n\n# Do stuff here\n```\n\n```yaml\n# workflow.yml\n\n- uses: astral-sh/setup-uv@v3\n\n- run: uv run script.py\n```\n\n## Usage\n\n### `hachitool.set_output`\n\n[Set output parameters for a step](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter).\nTakes either:\n\n- a key as its first argument and a value as its second\n- a set of key-value pairs as either a dictionary or keyword arguments\n\n```python\nimport hachitool\n\n# All of these are equivalent\nhachitool.set_output(\"key\", \"value\")\nhachitool.set_output({\"key\": \"value\"})\nhachitool.set_output(key=\"value\")\n```\n\n### `hachitool.set_env`\n\n[Set environment variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable).\nTakes either:\n\n- a key as its first argument and a value as its second\n- a set of key-value pairs as either a dictionary or keyword arguments\n\n```python\nimport hachitool\n\n# All of these are equivalent\nhachitool.set_env(\"key\", \"value\")\nhachitool.set_env({\"key\": \"value\"})\nhachitool.set_env(key=\"value\")\n```\n\n### `hachitool.add_path`\n\nAppend something to the system path.\n\n```python\nimport hachitool\n\nhachitool.add_path(\"/absolute/or/relative/path\")\n```\n\n### `hachitool.summary.add`\n\nAdd content to\nthe [step summary](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary).\nSupports [GitHub-flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).\n\n```python\nimport hachitool\n\nhachitool.summary.add(\"this is a summary\")\n```\n\n> [!TIP]\n> Calling `hachitool.summary` directly does the same thing:\n> ```python\n> import hachitool\n> \n> hachitool.summary(\"this is a summary\")\n> ```\n\nIf the keyword-only `overwrite` argument is `True`, existing summary content will be erased:\n\n```python\nimport hachitool\n\nhachitool.summary.add(\"this is a summary\", overwrite=True)\n```\n\n### `hachitool.summary.clear`\n\nClear the step summary.\n\n```python\nimport hachitool\n\nhachitool.summary.clear()\n```\n\n### `hachitool.mask`\n\n[Mask a value](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log).\n\n```python\nimport hachitool\n\nhachitool.mask(\"super secret value\")\n```\n\n### `hachitool.log`\n\nPrint a message to the log. Takes the following arguments:\n\n| **Argument** | **Type** | **Description** | **Required?** |\n|--------------|-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|---------------|\n| `level` | `\"debug\"` \\| `\"notice\"` \\| `\"warning\"` \\| `\"error\"` | The log level of the message. | Yes |\n| `message` | `str` | The message to print. | Yes |\n| `file` | `str` | The path to a file to annotate with the message. | No |\n| `line` | `int` \\| `tuple[int, int]` | The line(s) of `file` to annotate with the message. A tuple will be interpreted as a pair of starting and ending lines. | No |\n| `column` | `int` \\| `tuple[int, int]` | The column(s) of `file` to annotate with the message. A tuple will be interpreted as a pair of starting and ending columns. | No | | \n\n`level` and `message` are the first and second positional arguments, respectively.\n`file`, `line`, and `column` are keyword-only.\n\n```python\nimport hachitool\n\nhachitool.log(\"notice\", \"this is a notice message\", file=\"main.py\", line=1, column=6)\n\n# Using tuples for `line` and `column`\nhachitool.log(\"notice\", \"this is a notic message\", file=\"main.py\", line=(1, 5), column=(6, 10))\n```\n\n### `hachitool.debug`, `hachitool.notice`, `hachitool.warning`, `hachitool.error`\n\nPrint a `debug`, `notice`, `warning`, or `error` message to the log, respectively. Takes all arguments of\n`hachitool.log` except for `level`.\n\n```python\nimport hachitool\n\nhachitool.debug(\"this is a debug message\")\nhachitool.notice(\"this is a notice message\")\nhachitool.warning(\"this is a warning message\")\nhachitool.error(\"this is an error message\")\n```\n\n### `hachitool.fail`\n\nOptionally print an error-level message, then fail the workflow. Takes an optional `exit_code` argument\nthat must be an integer greater than or equal to 1. Additionally takes all arguments of `hachitool.error`,\nexcept `message` is optional.\n\n```python\nimport hachitool\n\nhachitool.fail(\"something went wrong\", exit_code=1)\n```\n\n### `hachitool.log_group`\n\nAnything printed to the log inside this context manager will be nested inside an\n[expandable group](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#grouping-log-lines).\n\nTakes a mandatory `title` argument.\n\n```python\nimport hachitool\n\nwith hachitool.log_group(title=\"group title\"):\n print(\"I'm part of a log group!\")\n print(\"me too!\")\n print(\"me three!\")\n```\n\n### `hachitool.literal`\n\nNothing printed to the log inside this context manager will be interpreted as a workflow command.\n\n```python\nimport hachitool\n\nhachitool.warning(\"this is a warning message to show that commands are being processed\")\n\nwith hachitool.literal():\n hachitool.warning(\"this will not render as a warning because commands are not being processed\")\n\nhachitool.warning(\"this will render as a warning since commands are being processed again\")\n```",
"bugtrack_url": null,
"license": null,
"summary": "Utilities for working with Python scripts in GitHub Actions",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/celsiusnarhwal/hachitool/blob/main/CHANGELOG.md",
"Issues": "https://github.com/celsiusnarhwal/hachitool/issues",
"Repository": "https://github.com/celsiusnarhwal/hachitool"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bd2e927e6ac8a7b007f586ccee4d1ec51faa6b45ada90fc1812b5cdab3ee9dc6",
"md5": "9288281d3ea16fbc00f00240e66c045f",
"sha256": "6b95dee71e8f1a182ea4779a766da3737e1f6b10e861c52af43ba0cfddb61cf3"
},
"downloads": -1,
"filename": "hachitool-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9288281d3ea16fbc00f00240e66c045f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6707,
"upload_time": "2024-12-08T22:00:42",
"upload_time_iso_8601": "2024-12-08T22:00:42.800661Z",
"url": "https://files.pythonhosted.org/packages/bd/2e/927e6ac8a7b007f586ccee4d1ec51faa6b45ada90fc1812b5cdab3ee9dc6/hachitool-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a5d0b41a826b8387f4325a6093d6f965fe0c7a1fff0ebd103c67a568d68f6a7",
"md5": "df2dab9f0a3773780a31ab87ceeff6ff",
"sha256": "a7ae4ea7017f49c73bcb6983ca8a5dd8ccbfa6dacac07fd6461c3a5db3a9a4aa"
},
"downloads": -1,
"filename": "hachitool-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "df2dab9f0a3773780a31ab87ceeff6ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 5027,
"upload_time": "2024-12-08T22:00:44",
"upload_time_iso_8601": "2024-12-08T22:00:44.313292Z",
"url": "https://files.pythonhosted.org/packages/4a/5d/0b41a826b8387f4325a6093d6f965fe0c7a1fff0ebd103c67a568d68f6a7/hachitool-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 22:00:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "celsiusnarhwal",
"github_project": "hachitool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hachitool"
}
