Skip to main content

PyHalboy

A library for all things hypermedia. insipred by Halboy and Halboy.js

  • Create hypermedia resources
  • Marshal to and from plain python dicts
  • Navigate JSON+HAL APIs

API

Resources

With PyHalboy you can create resources, and pull information from them.

from pyhalboy import Resource

discountResource = Resource()
    .add_link('self', '/discounts/1256')
    .add_property('discountPercentage', 10)

itemResources = [
   Resource()
    .add_link('self', '/items/534')
    .add_property('price', 25.48)
]

resource = Resource()
      .add_link('self', '/orders/123')
      .add_link('creator', '/users/rob')
      .add_resource('discount', discountResource)
      .add_resource('items', itemResources)
      .add_property('state', 'dispatching')

resource.get_link('self')
// { href: '/orders/123' }

resource.get_href('self')
// '/orders/123'

resource.get_property('state')
// 'dispatching'

resource
  .get_resource('creator')
  .get_property('discountPercentage')
// 10

resource
  .get_resource('items')[0]
  .get_property('price')
// 25.48

Marshalling

You can create HAL resources from plain JS objects, and vice versa.

from pyhalboy import Resource

itemResources = [
   Resource()
    .add_link('self', '/items/534')
    .add_property('price', 25.48)
]

resource =
    new Resource()
      .add_link('self', '/orders/123')
      .add_link('creator', '/users/rob')
      .add_resource('items', itemResources)
      .add_property('state', 'dispatching')

resource.to_object()
// {
//   _links: {
//     self: { href: '/orders/123' },
//     creator: { href: '/users/rob' }
//   },
//   _embedded: {
//     items: [{
//       _links: {
//         self: { href: '/items/534' }
//       },
//       price: 25.48
//     }]
//   },
//   state: 'dispatching'
// }

Resource.from_object(resource.to_object())
  .get_href('self')
// '/orders/123'

Navigation

Provided you're calling a HAL+JSON API, you can discover the API and navigate through its links. When you've found what you want, you call navigator.resource() and you get a plain old HAL resource, which you can inspect using any of the methods above.

from pyhalboy import Navigator

//  GET / - 200 OK
//  {
//   "_links": {
//     "self": {
//       "href": "/"
//     },
//     "users": {
//       "href": "/users"
//     },
//     "user": {
//       "href": "/users/{id}",
//       "templated": true
//     }
//   }
// }

discovery_result = Navigator.discover('https://api.example.com/')
users_result =  discovery_result.get('users')

users_result.status()
// 200

users_result.location()
// 'https://api.example.com/users'

robResult =  discovery_result.get('user', {id :'rob'})

robResult.location()
// 'https://api.example.com/users/rob'

sue_result =  discovery_result.post('user', {
  'id': 'sue',
  'name': 'Sue',
  'title': 'Dev'
})

sue_result.location()
// 'https://api.example.com/users/sue'

sue_result
  .resource()
  .get_property('title')
// 'Dev'

Contribution

Feel free to submit PRs and raise bugs.

Publishing

Prior to publishing the package, you need to configure your PyPi credentials on your local machine. Follow the instructions in the poetry docs to do this.

To publish the package:

poetry publish 

Metadata

Release files for tobyclemson.pyhalboy 1.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tobyclemson.pyhalboy 1.0.8
File Size Uploaded Provenance Actions
tobyclemson_pyhalboy-1.0.8.tar.gz 6.1 kB Without provenance Details for tobyclemson_pyhalboy-1.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tobyclemson.pyhalboy 1.0.8
File Interpreter ABI Platform Actions
tobyclemson_pyhalboy-1.0.8-py3-none-any.whl Python 3 none any Details for tobyclemson_pyhalboy-1.0.8-py3-none-any.whl

Total release size: 13.2 kB

Release files / tobyclemson_pyhalboy-1.0.8.tar.gz

Download URL tobyclemson_pyhalboy-1.0.8.tar.gz
Size 6.1 kB
Tags Source
SHA-256 checksum
How to use checksums
852a5d9c0102e4caae7bec63a03b6e1973dac9ad13d6025984293a279b46a82b
BLAKE2b-256 checksum
How to use checksums
3915652050f41367a9b061ec0ff0d67ef10772ef97aadf3d04b6f3776a333f85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.11.6 Darwin/24.1.0

Release files / tobyclemson_pyhalboy-1.0.8-py3-none-any.whl

Download URL tobyclemson_pyhalboy-1.0.8-py3-none-any.whl
Size 7.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4638f6197dee4b096a76cc1e0911887379ac1210861778bd80d8f1fbcca6dfbc
BLAKE2b-256 checksum
How to use checksums
d1304c1bc2340bbfc8c46e8574968562820860791c553941b2b25f2fb64cc25c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.11.6 Darwin/24.1.0

Security for tobyclemson.pyhalboy 1.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.8 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page