kylef / draughtsman

API Blueprint Parser for Python 3

Draughtsman

API Blueprint Parser for Python 3. Draughtsman is a Python binding for the API Blueprint parser drafter.

Installation

$ pip install draughtsman

Draughtsman requires the drafter library installed onto your system. Consult the drafter installation instructions for further information. Using Homebrew on macOS, Drafter can be installed via:

$ brew install drafter

Usage

>>> from draughtsman import parse
>>>
>>> parse_result = parse('# My API')
>>> parse_result.api.title.defract
'My API'

Draughtsman provides a parse function which returns a Refract ParseResult. See Python Refract for more information interacting with the parse result.

CLI

Draughtsman provides a convenience shell to parse an API Blueprint and interact with the parse result.

$ python -m draughtsman example.apib
>>> parse_result
<ParseResult content=[<Category content=[]>]>
>>> parse_result.annotations
[]
>>> parse_result.api.title
<String content='My API'>

draughtsman's Issues

Support Drafter 5

Compatibility with drafter 4.0.0-pre.0

Hello again 👋

I've compiled drafter 4.0.0-pre.0 from source as mentioned in apiaryio/drafter#542 (comment) Draughtsman works as documented with drafter 3.2.7, but I'm now getting some errors with the new version e.g:

>>> from draughtsman import parse
>>> parse('# My API')

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/path/to/stuff/lib/python3.5/site-packages/draughtsman/__init__.py", line 39, in parse
    return deserialiser.deserialise(string)
  File "/path/to/stuff/lib/python3.5/site-packages/refract/json.py", line 145, in deserialise
    return self.deserialise_dict(json.loads(element_json))
  File "/usr/lib/python3.5/json/__init__.py", line 319, in loads
    return _default_decoder.decode(s)
  File "/usr/lib/python3.5/json/decoder.py", line 339, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "/usr/lib/python3.5/json/decoder.py", line 357, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

>>> from draughtsman import parse
>>> bp = """
... FORMAT: 1A
... 
... # My API
... """
>>> parse(bp)

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/path/to/stuff/lib/python3.5/site-packages/draughtsman/__init__.py", line 37, in parse
    string = ffi.string(output[0]).decode('utf-8')
  File "/path/to/stuff/lib/python3.5/site-packages/cffi/api.py", line 309, in string
    return self._backend.string(cdata, maxlen)
RuntimeError: cannot use string() on <cdata 'char *' NULL>

Seems like maybe the first one is related to the new Refract 1.0 JSON Serialisation format ? Not so sure about the second..

Add CI to test against different major Drafter versions

Using GitHub Actions.

Unable to use on OSX

Hi there,

I'm having a few problems with getting draughtsman to work on OSX. I'm using pyenv with 3.6.5.

1. [Install link](brew install --HEAD
   https://raw.github.com/apiaryio/drafter/master/tools/homebrew/drafter.rb) in README.md is broken
2. when installing with brew install drafter (which installs drafter vesion 3.2.7), draughtsman throws the following error on import:\

In [1]: import draughtsman
---------------------------------------------------------------------------
OSError                                   Traceback (most recent call last)
<ipython-input-1-613fbf71acc2> in <module>()
----> 1 import draughtsman

~/.pyenv/versions/3.6.5/lib/python3.6/site-packages/draughtsman/__init__.py in <module>()
     23 ''')
     24
---> 25 drafter = ffi.dlopen('drafter')
     26
     27

~/.pyenv/versions/3.6.5/lib/python3.6/site-packages/cffi/api.py in dlopen(self, name, flags)
    139         assert isinstance(name, basestring) or name is None
    140         with self._lock:
--> 141             lib, function_cache = _make_ffi_library(self, name, flags)
    142             self._function_caches.append(function_cache)
    143             self._libraries.append(lib)

~/.pyenv/versions/3.6.5/lib/python3.6/site-packages/cffi/api.py in _make_ffi_library(ffi, libname, flags)
    800 def _make_ffi_library(ffi, libname, flags):
    801     backend = ffi._backend
--> 802     backendlib = _load_backend_lib(backend, libname, flags)
    803     #
    804     def accessor_function(name):

~/.pyenv/versions/3.6.5/lib/python3.6/site-packages/cffi/api.py in _load_backend_lib(backend, name, flags)
    795         if first_error is not None:
    796             msg = "%s.  Additionally, %s" % (first_error, msg)
--> 797         raise OSError(msg)
    798     return backend.load_library(path, flags)
    799

OSError: ctypes.util.find_library() did not manage to locate a library called 'drafter'

I've looked around, but I haven't found anybody with a similar issue.

Thank you.