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 pyhalboy 1.3.0

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

Source distribution (sdist)

Source distribution for pyhalboy 1.3.0
File Size Uploaded Provenance Actions
pyhalboy-1.3.0.tar.gz 6.2 kB Without provenance Details for pyhalboy-1.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 13.2 kB

Release files / pyhalboy-1.3.0.tar.gz

Download URL pyhalboy-1.3.0.tar.gz
Size 6.2 kB
Tags Source
SHA-256 checksum
How to use checksums
28967d7511b07fa341b4e5913c1cff5e4613549e85ad5997b5fc152dc879162c
BLAKE2b-256 checksum
How to use checksums
eb08ddf9a679d47ba5ef3aa80ad1cac3d33ad3aacdc4b94f90888dcff2d2bcaa
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 / pyhalboy-1.3.0-py3-none-any.whl

Download URL pyhalboy-1.3.0-py3-none-any.whl
Size 7.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
795b6a6f4e89f889cf32a487e3f329f07cb80168f47f728aa1619a6d4b52857c
BLAKE2b-256 checksum
How to use checksums
b472816d215bfb5d744569d9b1b34d470d79188a6eca836096f8853d221b56c6
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 pyhalboy 1.3.0

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.

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