Skip to main content

Declarative plain-text specifications for objects

Project description

mdspec

"Declarative Model Specifications, from markdown-ish plain text files"

Looking at defining models / object specification in "plain text" for working w/ designers & clients.

This is very much a hacky work-in-progress, / working out loud playground at the moment.

The big idea:

Tests in Python or JS are great, but not accessible to non-coders. Features need to be defined somehow, and agreed between parties.

Gerkin is alright for describing functional requirements - but the whole idea of "given/when/then" is very process oriented - whereas on Django / Wagtail / CMS based sites often have many objects defined which automatically implement a tonne of features. (ie, A Page model with a few fields).

They're implemented declaratively, not functionally.

Could we have something similar to gerkin for models / blocks that are declarative not functional?

And could we use a declarative style of specification, but in a plain-english type of format to facilitate that in a way that's easy to understand & share betweeen techies & non-techies?

Example:

(syntax subject to change)

# HomePage
HomePage is a Page Type.
It has these fields:
 - title: required, text, maximum 100 characters
 - banner: image, optional
 - banner: text, optional
 - contents (the main contents of the page...)

The contents field is a StreamField.
It has these blocks:
 - richtext
 - image
 - raw-html
 - contact-form

## Block definitions...

richtext is a Wagtail Block.
It has these fields:
 - contents
 - style

image is a Wagtail Block.
It has these fields:
 - image (the link to the image itself...)
 - caption
 - link

...

Which, in theory, is relatively easy to understand for non-techies, and renders nicely as markdown. It can be rendered out, signed off, etc.

It's structured though, so it can be parsed (by this project) into something we can then travese / execute as part of CI / tests.

it results in something like:

{
    "_name": "HomePage",
    "_type": "Page",
    "fields": [
        ["title", "required", "text", "maximum 100 characters"],
        ["banner", "image", "optional"],
        ["contents"]
    ]
},

{
    "_name": "contents",
    "_type": "StreamField",
    "blocks": [
        ["richtext"]
        ["image"]
        ["raw-html"]
        ...
    ]
},

...

etc. (Example, not actual format. But structured something like that...)

Now we have that specification as (dict / JSON / structured) objects, it's pretty easy to write tests that automatically find each defined page type, check that it has all required fields, or whatever.

We could also have tests that check that the admin page for each page type actually has all of those fields as form fields in the admin.

Once you get to anywhere where logic is involved (eg, templates, output) then switching to gerken based cases makes a lot more sense, this spec type would just be for things which are structurely "defined" rather than functionally implemented... (if that makes sense?)

Thoughts:

  • anything in brakets (like this) is considered a comment, and ignored?
  • markdown titles are ignored too.
  • how can we have nice sections for random implementaion notes? maybe use markdown quotation > text blocks? Should those be stored to use as docstrings in generation? or better not?

to play:

python3 mdspec/parser.py examples/pages.md

and it should output a structured version of the contents. (There will be tests run with make test too - WIP...)

What could we do with this?

  • Use it just as a structured way to define models / pages / etc.
  • Get sign off from different teams (BE / FE / Design / client...)
  • Run acceptance tests automatically off the structured data.
  • Generate initial model python code / tests / templates / etc?

Example thoughts:

TeamPage is a Page Type
it has these fields:
 - title
 - top_contents
 - below_contents
it has these connections:
 - team: Person, many via "TeamPerson"

How much worse is this in gerkin?

Scenario:
  Given an Index Page
   When I add a child page
   Then I should be able to add a TeamPage

and

Given a TeamPage
 When I edit it in wagtail
 Then I should be able to edit the title field
  And I should be able to edit the top_contents field
  ...

hm... it's so verbose. But functional spec.

I guess with this kind of declarative spec, we can pass that into other tests?

 Given <pagetype>
  When I edit it in wagtail
  Then I should be able to edit all defined fields

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mdspec-0.0.2.tar.gz (5.5 kB view details)

Uploaded Source

Built Distribution

mdspec-0.0.2-py3-none-any.whl (5.0 kB view details)

Uploaded Python 3

File details

Details for the file mdspec-0.0.2.tar.gz.

File metadata

  • Download URL: mdspec-0.0.2.tar.gz
  • Upload date:
  • Size: 5.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.2 CPython/3.10.0 Darwin/22.2.0

File hashes

Hashes for mdspec-0.0.2.tar.gz
Algorithm Hash digest
SHA256 ad3823a4726c9fdf488c8bfd65a51c0cd5efc7ab1f80faa0936b1d643ef635be
MD5 cc35e438d51fe771880d8bba66430e31
BLAKE2b-256 74da1d80cd8598611fde7c68e256a6bf207e6b31981f63966d9fbf8b0cd3f9d6

See more details on using hashes here.

File details

Details for the file mdspec-0.0.2-py3-none-any.whl.

File metadata

  • Download URL: mdspec-0.0.2-py3-none-any.whl
  • Upload date:
  • Size: 5.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.2 CPython/3.10.0 Darwin/22.2.0

File hashes

Hashes for mdspec-0.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 681c949fc3830376215a656b4ae3b5c3f6047527d392e7e64865915ea23e0499
MD5 a6254c1e98d775723796594fd438f07e
BLAKE2b-256 fce887319067aad856cb147ef1c54afa70278cab89f7ae33b8d185aca76e9774

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page