Overview¶

docs
tests
package

https://syntactic.readthedocs.io/

Customizable syntax for Python.

Possible uses¶

Experimenting with possible language features.
Boilerplate reduction.

Examples¶

Unicode lambdas¶

from __syntax__ import unicode_lambdas

increment = λx: x + 1

is equivalent to

increment = lambda x: x + 1

SQL template literals¶

Embedded sql:

from __syntax__ import sql_literals

engine.query(sql`SELECT author FROM books WHERE name = {book} AND author = {author}`)

is equivalent to:

engine.query('SELECT author FROM books WHERE name = ? AND author = ?', [book, author])

Limitations¶

The example transformers are written in a fragile way. They are intended only as inspiration rather than production-ready transformers. If you want to add some production-ready ones, pull-requests are welcome.

Contents¶

Overview¶

docs
tests
package

https://syntactic.readthedocs.io/

Customizable syntax for Python.

Possible uses¶

Experimenting with possible language features.
Boilerplate reduction.

Examples¶

Unicode lambdas¶

from __syntax__ import unicode_lambdas

increment = λx: x + 1

is equivalent to

increment = lambda x: x + 1

SQL template literals¶

Embedded sql:

from __syntax__ import sql_literals

engine.query(sql`SELECT author FROM books WHERE name = {book} AND author = {author}`)

is equivalent to:

engine.query('SELECT author FROM books WHERE name = ? AND author = ?', [book, author])

Limitations¶

The example transformers are written in a fragile way. They are intended only as inspiration rather than production-ready transformers. If you want to add some production-ready ones, pull-requests are welcome.

Installation¶

Basic¶

With pip:

pip install syntactic

With Poetry:

poetry add syntactic

With optional command-line tool¶

With pip:

pip install 'syntactic[cli]'

With Poetry:

poetry add 'syntactic[cli]'

Usage¶

Create a new custom syntax¶

1. Make a transformer¶

Create a function that takes the original unicode source string and returns a new unicode source string.

def unicode_lambdas(source: str) -> str:
    """Convert unicode lambdas into regular lambdas."""
    return source.replace("λ", "lambda ")

Put that function in a module named __syntax__.py. It may be in a package.

Use a custom syntax¶

Install syntactic.
Install a module that provides a custom syntax plugin.
In the module where you want to use the syntax, put the syntactic coding declaration at the top of the file.
```
# coding: syntactic
```
In the module where you want to use the syntax, import the desired syntax.
```
from __syntax__ import unicode_lambdas
```

If the module is in a package, namespace the import as normal. For example:

from syntactic.examples.__syntax__ import unicode_lambdas

Write code using the custom syntax. The full module should look like this:

# coding: syntactic

from __syntax__ import unicode_lambdas

add_one = λx: x+1

print(add_one(1))

Run the module using the python environment where syntactic is installed. The output should be:
```
2
```

View transformed syntax¶

View the expanded form of a Python file by using the optional command-line tool.

Ensure Syntactic’s cli extra is installed.
Use python -m syntactic show <filename>.

Reference¶

syntactic package¶

Submodules¶

syntactic.app module¶

Support for custom syntax.

class syntactic.app.IncrementalDecoder(errors='strict')[source]¶

Bases: codecs.BufferedIncrementalDecoder

A buffered incremental decoder for custom syntax.

class syntactic.app.StreamReader(stream, errors='strict')[source]¶

Bases: encodings.utf_8.StreamReader

decode is deferred to support better error messages

stream¶: Get the stream.

syntactic.app.decode(source_bytes, errors='strict')[source]¶: Decode the utf-8 input and transform it with the named transformers.

syntactic.app.get_transformer_pairs(source)[source]¶

Return the module and function names of requested transformers.

Searches for from __syntax__ import ....

Return type:	`List`[`Tuple`[`str`, `str`]]

syntactic.app.main()[source]¶: Register the codec with Python.

syntactic.cli module¶

syntactic.examples module¶

Module contents¶

Syntactic provides custom syntax for Python.

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug reports¶

When reporting a bug please include:

Your operating system name and version.

Any details about your local setup that might be helpful in troubleshooting.

Detailed steps to reproduce the bug.

Documentation improvements¶

syntactic could always use more documentation, whether as part of the official syntactic docs, in docstrings, or even on the web in blog posts, articles, and such.

Feature requests and feedback¶

The best way to send feedback is to file an issue at https://github.com/metatooling/syntactic/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that code contributions are welcome :)

Development¶

To set up syntactic for local development:

Fork syntactic (look for the “Fork” button).

Clone your fork locally:

git clone git@github.com:your_name_here/syntactic.git

Create a branch for local development:
```
git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, run all the checks, doc builder and spell checker with tox one command:
```
tox
```

Commit your changes and push your branch to GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

If you need some code review or feedback while you’re developing the code just make the pull request.

For merging, you should:

Include passing tests (run tox) [1].
Update documentation when there’s new API, functionality etc.
Add a file in changelog.d/ describing the changes. The filename should be {id}.{type}.rst, where {id} is the number of the GitHub issue or pull request and {type} is one of breaking (for breaking changes), deprecation (for deprecations), or change (for non-breaking changes). For example, to add a new feature requested in GitHub issue #1234, add a file called changelog.d/1234.change.rst describing the change.
Add yourself to AUTHORS.rst.

[1]	If you don’t have all the necessary python versions available locally you can rely on Travis - it will run the tests for each change you add in the pull request. It will be slower though …

Tips¶

To run a subset of tests:

tox -e envname -- pytest -k test_myfeature

To run all the test environments in parallel (you need to pip install detox):

detox

Authors¶

Metatooling - https://github.com/metatooling/

Changelog¶

0.1.0 (2019-12-30)¶

Changes¶

First release on PyPI.

—

Overview¶

Possible uses¶

Examples¶

Unicode lambdas¶

SQL template literals¶

Limitations¶

Related work¶

Contents¶

Overview¶

Possible uses¶

Examples¶

Unicode lambdas¶

SQL template literals¶

Limitations¶

Related work¶

Installation¶

Basic¶

With optional command-line tool¶

Usage¶

Create a new custom syntax¶

1. Make a transformer¶

Use a custom syntax¶

View transformed syntax¶

Reference¶

syntactic package¶

Submodules¶

syntactic.app module¶

syntactic.cli module¶

syntactic.examples module¶

Module contents¶

Contributing¶

Bug reports¶

Documentation improvements¶

Feature requests and feedback¶

Development¶

Pull Request Guidelines¶

Tips¶

Authors¶

Changelog¶

0.1.0 (2019-12-30)¶

Changes¶

Indices and tables¶