jupyter-hurl-kernel 0.0.2

A Jupyter kernel for running Hurl commands

Jupyter Hurl Kernel

A Jupyter kernel for executing Hurl commands directly in Jupyter notebooks.

What is Hurl?

Hurl is a command line tool that runs HTTP requests defined in a simple plain text format. It's designed for testing HTTP endpoints, APIs, and web services. Learn more at hurl.dev.

Features

• Execute Hurl commands directly in Jupyter notebook cells
• Get HTTP responses displayed in the notebook
• Supports all Hurl syntax and features
• Easy to install and use

Prerequisites

1. Python 3.13+ - This project requires Python 3.13 or higher
2. Hurl - Install Hurl from hurl.dev/docs/installation.html

Installing Hurl

On macOS:

brew install hurl

On Linux:

# Debian/Ubuntu
curl -LO https://github.com/Orange-OpenSource/hurl/releases/latest/download/hurl_amd64.deb
sudo dpkg -i hurl_amd64.deb

# Or build from source
cargo install hurl

On Windows:

# Using Scoop
scoop install hurl

# Or using Chocolatey
choco install hurl

Verify the installation:

hurl --version

Installation

From PyPI (Recommended)

pip install jupyter-hurl-kernel
install-hurl-kernel

For installation in a virtual environment:

pip install jupyter-hurl-kernel
install-hurl-kernel --sys-prefix

From Source

1. Clone or download this repository:

git clone https://github.com/micedre/jupyter-hurl-kernel.git
cd jupyter-hurl-kernel

2. Install the package using uv:

uv pip install -e .

3. Install the Jupyter kernel:

install-hurl-kernel

For installation in a virtual environment:

install-hurl-kernel --sys-prefix

4. Verify the kernel is installed:

jupyter kernelspec list

You should see hurl in the list of available kernels.

Usage

1. Start Jupyter Notebook or JupyterLab:

jupyter notebook
# or
jupyter lab

2. Create a new notebook and select "Hurl" as the kernel

3. Write Hurl commands in notebook cells:

Example 1: Simple GET request

GET https://www.insee.fr

Example 2: GET with headers

GET https://api.github.com/users/octocat
User-Agent: MyApp/1.0
Accept: application/json

Example 3: POST request

POST https://httpbin.org/post
Content-Type: application/json
{
  "name": "John Doe",
  "age": 30
}

Example 4: Testing with assertions

GET https://httpbin.org/json
HTTP 200
[Asserts]
jsonpath "$.slideshow.title" == "Sample Slide Show"

Example 5: Include response headers (using %%include)

%%include
GET https://api.github.com/users/octocat

Example 6: Verbose output with all details (using %%verbose)

%%verbose
GET https://api.github.com/users/octocat

4. Run the cell (Shift+Enter) to execute the Hurl command

The kernel will display:

• HTTP response output
• Any errors or validation failures

Magic Lines

You can control the output level using magic lines at the start of cells. These magic lines correspond to Hurl's command-line flags:

• No magic line (default) - Shows only the response body
• %%include - Shows response headers and body (equivalent to hurl --include)
• %%verbose - Shows all information including request details, response headers, body, timing, etc. (equivalent to hurl --verbose)

Examples:

Normal output (body only):

GET https://www.insee.fr

Include mode (headers + body):

%%include
GET https://www.insee.fr

Verbose mode (complete details):

%%verbose
GET https://www.insee.fr

Features

Autocompletion

The kernel provides intelligent autocompletion for Hurl syntax. Press Tab to trigger autocompletion:

• HTTP Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, etc.
• Common Headers: Content-Type:, Authorization:, Accept:, User-Agent:, etc.
• Hurl Sections: [Asserts], [Captures], [QueryStringParams], [FormParams], etc.
• Magic Lines: %%include, %%verbose
• Content Types: When typing Content-Type:, get suggestions for common MIME types

The autocompletion is context-aware and will suggest relevant completions based on where your cursor is positioned.

Documentation Tooltips

Hover over or press Shift+Tab on keywords to see documentation:

• HTTP Methods: See descriptions of what each HTTP method does
• Hurl Sections: Get examples and explanations for each section type
• Magic Lines: Learn what each magic line does

Example: Place your cursor on GET and press Shift+Tab to see:

HTTP GET Method

GET method requests a representation of the specified resource.
Requests using GET should only retrieve data.

Syntax Highlighting

The kernel includes a custom CodeMirror mode that provides syntax highlighting for Hurl files:

• HTTP Methods (GET, POST, etc.) - highlighted as keywords
• URLs - highlighted as strings
• Headers - highlighted as attributes
• Section headers ([Asserts], [Captures], etc.) - highlighted as headers
• Magic lines (%%include, %%verbose) - highlighted as meta
• Assertions (status, jsonpath, etc.) - highlighted as builtins
• Operators (==, !=, >, <, etc.) - highlighted as operators
• Numbers and strings - appropriately colored
• Comments (#) - highlighted as comments
• JSONPath and XPath expressions - highlighted as variables

The syntax highlighting is automatically installed when you run install-hurl-kernel. After installation, you may need to refresh your browser for the highlighting to take effect.

How It Works

The kernel works by:

1. Taking the Hurl code from the notebook cell
2. Writing it to a temporary .hurl file
3. Executing hurl --color <file>
4. Capturing and displaying the output in the notebook
5. Cleaning up the temporary file

Troubleshooting

Code completion or syntax highlighting not working

If autocompletion or syntax highlighting isn't working on your Jupyter server, see the detailed TROUBLESHOOTING.md guide.

Quick fixes:

1. Clear browser cache and hard refresh (Ctrl+Shift+R)
2. Restart Jupyter server
3. Reinstall kernel: install-hurl-kernel --sys-prefix (for servers/virtual environments)
4. If using JupyterLab 4, try classic Jupyter Notebook instead: jupyter notebook

"hurl is not installed" error

Make sure Hurl is installed and available in your PATH:

which hurl
hurl --version

Kernel not appearing in Jupyter

Try reinstalling the kernel:

install-hurl-kernel --user
jupyter kernelspec list

Command timeout

By default, commands timeout after 30 seconds. For long-running requests, this can be adjusted in the kernel code.

Development

To modify the kernel:

1. Clone the repository:

   git clone https://github.com/micedre/jupyter-hurl-kernel.git
   cd jupyter-hurl-kernel
   

2. Install in development mode:

   uv pip install -e .
   install-hurl-kernel --sys-prefix
   

3. Make your changes to the kernel code in src/jupyter_hurl_kernel/

4. Restart your Jupyter notebook kernel to test changes

Running Tests

# Build the package to verify
uv build

# Check the distribution
uv tool run twine check dist/*

Releasing a New Version

This project uses GitHub Actions with PyPI trusted publishing for releases. The version is automatically bumped from the release tag.

1. Commit and push your changes to master
2. Create and push a new tag with the version number:

   git tag v0.1.1
   git push origin v0.1.1
   

3. Create a GitHub release from the tag
4. The GitHub Action will automatically:
   • Extract the version from the tag
   • Update pyproject.toml with the new version
   • Commit the version bump back to the repository
   • Build and publish to PyPI

Note: You don't need to manually update the version in pyproject.toml - it's automatically updated from the Git tag.

For more details on setting up PyPI trusted publishing, see .github/PYPI_SETUP.md.

Uninstallation

To remove the kernel:

jupyter kernelspec uninstall hurl

To uninstall the package:

uv pip uninstall jupyter-hurl-kernel

License

This project is open source and available under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources

• Hurl Documentation
• Hurl Tutorial
• Jupyter Kernel Documentation