Unpythonic

With the arrival of [conditions and restarts](http://www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html), and a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) server, I think it is now fair to say `unpythonic` contains an ad-hoc, informally-specified, slow implementation of half of Common Lisp. To avoid *bug-ridden*, we have tests - but it's not entirely impossible for some to have slipped through. If you find one, please file an issue [in the tracker](https://github.com/Technologicat/unpythonic/issues).

This release welcomes the first external contribution! Thanks to aisha-w for the much improved organization and presentation of the documentation!

**Language version**:

We target **Python 3.6**. Now we test on both **CPython** and **PyPy3**.

Rumors of the demise of Python 3.4 support are exaggerated. While the testing of `unpythonic` has moved to 3.6, there neither is nor will there be any active effort to intentionally drop 3.4 support until `unpythonic` reaches 0.15.0.

That is, support for 3.4 will likely be dropped with the arrival of the next batch of breaking changes. The current plan is visible in the roadmap [as the 0.15.0 milestone](https://github.com/Technologicat/unpythonic/milestone/1).

If you're still stuck on 3.4 and find something in the latest `unpythonic` 0.14.x doesn't work there, please file an issue. (Support for 0.14.x will end once 0.15 is released, but not before.)

**New**:

- Improve organization and presentation of documentation (28).
- Macro README: Emacs syntax highlighting for `unpythonic.syntax` and MacroPy.
- **Resumable exceptions**, a.k.a. *conditions and restarts*. One of the famous killer features of Common Lisp. Drawing inspiration from [python-cl-conditions](https://github.com/svetlyak40wt/python-cl-conditions/) by Alexander Artemenko. See `with restarts` (Common Lisp equivalent: `RESTART-CASE`), `with handlers` (`HANDLER-BIND`), `signal` (`SIGNAL`), `invoke` (`INVOKE-RESTART`). Many convenience forms are also exported; see `unpythonic.conditions` for a full list. For an introduction to conditions, see [Chapter 19 in Practical Common Lisp by Peter Seibel](http://www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html).
- **REPL server** and client. Interactively hot-patch your running Python program! Another of the famous killer features of Common Lisp. The server is daemonic, listening for connections in a background thread. (Don't worry, it's strictly opt-in.) See `unpythonic.net.server` and `unpythonic.net.client`.
- *Batteries for network programming*:
- `unpythonic.net.msg`: A simplistic message protocol for sending message data over a stream-based transport (such as TCP).
- `unpythonic.net.ptyproxy`: Proxy between a Linux [PTY](https://en.wikipedia.org/wiki/Pseudoterminal) and a network socket. Useful for serving terminal utilities over the network. This doesn't use `pty.spawn`, so Python libraries that expect to run in a terminal are also welcome. See `unpythonic.net.server` for a usage example.
- `unpythonic.net.util`: Miscellaneous small utilities.
- `fix`: Break infinite recursion cycles (for pure functions). Drawing inspiration from original implementations by [Matthew Might](http://matt.might.net/articles/parsing-with-derivatives/) and [Per Vognsen](https://gist.github.com/pervognsen/8dafe21038f3b513693e).
- More batteries for itertools:
- `fixpoint`: Arithmetic fixed-point finder (not to be confused with `fix`).
- `within`: Yield items from iterable until successive iterates are close enough (useful with [Cauchy sequences](https://en.wikipedia.org/wiki/Cauchy_sequence)).
- `chunked`: Split an iterable into constant-length chunks.
- `lastn`: Yield the last `n` items from an iterable.
- `pad`: Extend iterable to length `n` with a `fillvalue`.
- `interleave`: For example, `interleave(['a', 'b', 'c'], ['+', '*']) --> ['a', '+', 'b', '*', 'c']`. Interleave items from several iterables, slightly differently from `zip`.
- `find`: From an iterable, get the first item matching a given predicate. Convenience function.
- `powerset`: Compute the power set (set of all subsets) of an iterable. Works also for infinite iterables.
- `CountingIterator`: Count how many items have been yielded, as a side effect.
- `slurp`: Extract all items from a `queue.Queue` (until it is empty) into a list, returning that list.
- `map`: Curry-friendly thin wrapper for the builtin `map`, making it mandatory to specify at least one iterable.
- `running_minmax`, `minmax`: Extract both min and max in one pass over an iterable. The `running_` variant is a scan and returns a generator; the just-give-me-the-final-result variant is a fold.
- `ulp`: Given a float `x`, return the value of the unit in the last place (the "least significant bit"). At `x = 1.0`, this is the [machine epsilon](https://en.wikipedia.org/wiki/Machine_epsilon), by definition of the machine epsilon.
- `partition_int`: split a small positive integer, in all possible ways, into smaller integers that sum to it.
- `dyn` now supports rebinding, using the assignment syntax `dyn.x = 42`. To mass-update atomically, see `dyn.update`.
- `box` now supports `.set(newvalue)` to rebind (returns the new value as a convenience), and `unbox(b)` to extract contents. Syntactic sugar for rebinding is `b << newvalue` (where `b` is a box).
- `ThreadLocalBox`: A box with thread-local contents. It also holds a default object, which is used when a particular thread has not placed any object into the box.
- `Some`: An immutable box. Useful for optional fields; tell apart the presence of a `None` value (`Some(None)`) from the absence of a value (`None`).
- `Shim`: A shim holds a `box` or a `ThreadLocalBox`, and redirects attribute accesses to whatever object is currently in the box. The point is that the object in the box can be replaced with a different one later, while keeping the attribute proxy in place. One use case is to redirect standard output only in particular threads.
- `islice` now supports negative start and stop. (**Caution**: no negative step; and it must consume the whole iterable to determine where it ends, if at all.)
- `async_raise`: Inject KeyboardInterrupt into an arbitrary thread. (*CPython only*.)
- `resolve_bindings`: Get the parameter bindings a given callable would establish if it was called with the given args and kwargs. This is mainly of interest for implementing memoizers, since this allows them to see (e.g.) `f(1)` and `f(a=1)` as the same thing for `def f(a): pass`.
- `Singleton`: a base class for singletons that interacts properly with `pickle`. The pattern is slightly pythonified; instead of silently returning the same instance, attempting to invoke the constructor while an instance already exists raises `TypeError`. This solution separates concerns better; see [22](https://github.com/Technologicat/unpythonic/issues/22).
- `sym`: a lispy symbol type; or in plain English: a lightweight, human-readable, process-wide unique marker, that can be quickly compared to another such marker by object identity (`is`). These named symbols are *interned*. Supplying the same name to the constructor results in receiving the same object instance. Symbols survive a `pickle` roundtrip.
- `gensym`: a utility to create a new, unique *uninterned* symbol. Like the pythonic idiom `nonce = object()`, but with a human-readable label, and with `pickle` support. Object identity of gensyms is determined by an UUID, generated when the symbol is created. Gensyms also survive a `pickle` roundtrip.

**Experimental features**:

Each experimental feature is a provisional proof-of-concept, usually lacking battle-testing and polish. Details may still change in a backwards-incompatible way, or the whole feature may still be removed. Do not depend on it in production!

- **Multiple dispatch**. The `generic` decorator makes a generic function with multiple dispatch. Arity and type annotations determine which method of the generic function a specific call of the function is dispatched to.
- This essentially allows replacing the `if`/`elif` dynamic type checking boilerplate of polymorphic functions with type annotations on the function parameters, with support for features from the `typing` stdlib module.
- Inspired by the [multi-methods of CLOS](http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html) (the Common Lisp Object System), and the [generic functions of Julia](https://docs.julialang.org/en/v1/manual/methods/).
- `typed`: The little sister of the `generic` decorator. Restrict allowed argument types to one specific combination only.
- `isoftype`: The big sister of `isinstance`. Type check a value against a type specification at run time, with support for many (but not all) features from the [`typing`](https://docs.python.org/3/library/typing.html) module. This is the machinery that powers `generic` and `typed`.
- If you need a run-time type checker for serious general use, consider the [`typeguard`](https://github.com/agronholm/typeguard) library.

**Non-breaking changes**:

- `setescape`/`escape` have been renamed `catch`/`throw`, to match the standard terminology in the Lisp family. **The old nonstandard names are now deprecated, and will be removed in 0.15.0.**
- The parameters of `raisef` are now more pythonic, just the object `exc` and an optional keyword-only `cause`. **Old-style parameters are now deprecated, and will be removed in 0.15.0.** See [30](https://github.com/Technologicat/unpythonic/issues/30).
- `runpipe` and `getvalue` are now both replaced by a single unified name `exitpipe`. This is just a rename, with no functionality changes. **The old names are now deprecated, and will be removed in 0.15.0.**
- Accessing the `.x` attribute of a `box` directly is now deprecated. It does not work with `ThreadLocalBox`, which must handle things differently due to implementation reasons. Instead, use the API, which works for both types of boxes. `b << newvalue` (syntactic sugar) or `b.set(newvalue)` sends a different object into the box, and `unbox(b)` (syntactic sugar) or `b.get()` retrieves the current value.
- The `dbg[]` macro now works in the REPL, too. See [12](https://github.com/Technologicat/unpythonic/issues/12).
- The `namedlambda` block macro now also names lambdas that are:
- Passed as a named argument of a function call, as in ``foo(f=lambda ...: ...)``; or
- Inside a dictionary literal, with a literal string key, as in ``{"f": lambda ...: ...}``. See [40](https://github.com/Technologicat/unpythonic/issues/40).
- Move macro documentation to `doc/macros.md`. (Was `macro_extras/README.md`.)
- Add contribution guidelines, `HACKING.md`.

**Fixed**:

- Fix initialization crash in `lazyutil` if MacroPy is not installed.
- Fix bug in `identity` and `const` with zero args ([7](https://github.com/Technologicat/unpythonic/issues/7)).
- Use standard Python semantics for negative indices ([6](https://github.com/Technologicat/unpythonic/issues/6)).
- Escape continuation analysis in `unpythonic.syntax.util` now interprets also the literal name `throw` as invoking an escape continuation.
- Fix pickling of `frozendict` ([55](https://github.com/Technologicat/unpythonic/issues/55)).
- Fix spurious cache misses in memoizers ([26](https://github.com/Technologicat/unpythonic/issues/26)). The bug affected `memoize`, `gmemoize`, `fix` and `fixtco`.

---

**Language version**:

- Support Python 3.6. First released in 2016, supported until 2021, most distros should have it by now.
- This will be the final release that supports Python 3.4; upstream support for 3.4 ended in March 2019.

**New**:

- ``Popper``, a pop-while iterator.
- ``window``, a length-n sliding window iterator for general iterables.
- ``autoref[]`` can now be nested.
- ``dbg[]`` now supports also an expression variant, customizable by lexically assigning ``dbgprint_expr``. See the README on macros for details.

**Bugfixes**:

- Fix crash when SymPy or mpmath are not installed.
- ``mogrify`` is now part of the public API, as it should have been all along.
- Docs: Mention the ``mg`` function in the README.

**Non-breaking changes**:

- Future-proof ``namelambda`` for Python 3.8.
- Docs: ``dbg[]`` is now listed as a convenience feature in the README.

---

**Bugfixes**:

- ``setup.py``: macros are not zip safe, because ``ZipImporter`` fails to return source code for the module and MacroPy needs that.
- fix splicing in the ``do[]`` macro; ``ExpandedDoView`` should now work correctly
- fix lambda handling in the ``lazify`` macro
- fix ``dict_items`` handling in ``mogrify`` (fixes the use of the ``curry`` macro with code using ``frozendict``)

**New**:

- ``roview``: a read-only view into a sequence. Behaves mostly the same as ``view``, but has no ``__setitem__`` or ``reverse``.
- ``mg``: a decorator to mathify a gfunc, so that it will ``m()`` the generator instances it makes.
- The ``do[]`` macro now supports ``delete[name]`` to delete a local variable previously created in the same do-expression using ``local[name << value]``.
- ``envify`` block macro, to make formal parameters live in an unpythonic ``env``.
- ``autoref`` block macro, to implicitly reference attributes of an object (for reading only).

**Breaking changes**:

- The ``macropy3`` bootstrapper now takes the ``-m`` option; ``macropy3 -m somemod``, like ``python3 -m somemod``. The alternative is to specify a filename positionally; ``macropy3 somescript.py``, like ``python3 somescript.py``. In either case, the bootstrapper will import the module in a special mode that pretends its ``__name__ == '__main__'``, to allow using the pythonic conditional main idiom also in macro-enabled code.
- The constructor of the writable ``view`` now checks that the input is not read-only (``roview``, or a ``Sequence`` that is not also a ``MutableSequence``) before allowing creation of the writable view.
- ``env`` now checks finalization status also when deleting attrs (a finalized ``env`` cannot add or delete bindings)

**Non-breaking improvements**:

- ``env`` now provides also the ``collections.abc.MutableMapping`` API.
- The ``tco`` macro now skips nested ``continuations`` blocks (to allow [Lispython](https://github.com/Technologicat/pydialect/tree/master/lispython) in [Pydialect](https://github.com/Technologicat/pydialect) to support ``continuations``).
- ``setup.py`` now installs the ``macropy3`` bootstrapper.

---

**New**:

- `view`: writable, sliceable view into a sequence. Use like `view(lst)[::2]`. Can be nested (i.e. sliced again). Any access (read or write) goes through to the original underlying sequence. Can assign a scalar to a slice à la NumPy. Stores slices, not indices; works also if the length of the underlying sequence suddenly changes.
- `islice`: slice syntax support for `itertools.islice`, use like `islice(myiterable)[100:10:2]` or `islice(myiterable)[42]`. (It's essentially a curried function, where the second step uses the subscript syntax instead of the function call syntax.)
- `prod`: like `sum`, but computes the product. A missing battery.
- `iindex`: like `list.index`, but for iterables. A missing battery. (Makes sense mostly for memoized input.)
- `inn(x, iterable)`: contains-check (`x in iterable`) for monotonic infinite iterables, with [automatic](http://wiki.c2.com/?LazinessImpatienceHubris) termination.
- `getattrrec`, `setattrrec` (**rec**ursive): access underlying data in an onion of wrappers.
- `primes` and `fibonacci` generators, mainly intended for testing and usage examples.
- ``SequenceView`` and ``MutableSequenceView`` abstract base classes; ``view`` is a ``MutableSequenceView``.

**Breaking changes**:

- The `fup[]` utility macro to functionally update a sequence **is gone and has been replaced** by the `fup` utility function, with slightly changed syntax to accommodate. New syntax is like `fup(lst)[3:17:2] << values`. (This is a two-step curry utilizing the subscript and lshift operators.)
- `ShadowedSequence`, and hence also `fupdate`, now raise the semantically more appropriate `IndexError` (instead of the previous `ValueError`) if the replacement sequence is too short.
- `namelambda` now returns a modified copy; the original function object is no longer mutated.

**Non-breaking improvements**:

- `ShadowedSequence` now supports slicing (read-only), equality comparison, `str` and `repr`. Out-of-range access to a single item emits a meaningful error, like in `list`.
- `env` and `dyn` now provide the `collections.abc.Mapping` API.
- `cons` and friends: `BinaryTreeIterator` and `JackOfAllTradesIterator` now support arbitarily deep cons structures.

---

**New**:

- ``lazify`` macro: call-by-need for Python (a.k.a. lazy functions, like in Haskell)
- ``frozendict``: an immutable dictionary
- ``mogrify``: in-place ``map`` for mutable containers
- ``timer``: a context manager for performance testing
- `s`: create lazy mathematical sequences. For example, `s(1, ...)`, `s(1, 2, ...)`, `s(1, 2, 4, ...)` and `s(1, 2, ...)**2` are now valid Python. Regular function, no macros.
- `m`: endow any iterable with infix math support. (But be aware that after that, applying an operation meant for general iterables drops the math support; to restore it, `m(result)` again.)
- The ``unpythonic.llist`` module now provides ``JackOfAllTradesIterator`` that understands both trees and linked lists (with some compromises).
- ``nb`` macro: a silly ultralight math notebook.

**Breaking changes**:

- ``dyn``: the ``asdict`` and ``items`` methods now return a live view.
- The mutable single-item container ``Box`` and its data attribute ``value`` have been renamed to ``box`` and ``x``, respectively.
- ``namedlambda`` macro: Env-assignments are now processed lexically, just like regular assignments. Added support for let-bindings.
- ``curry`` macro: The special mode for uninspectables is now enabled lexically within the ``with curry`` block. Also, manual uses of the ``curry`` decorator (on both ``def`` and ``lambda``) are now detected, and in such cases the macro now skips adding the ``curry`` decorator.

**Non-breaking improvements**:

- ``namelambda`` now supports renaming any function object, and also multiple times.
- The single-item special binding syntax is now supported also by the bindings block of the ``dlet``, ``dletseq``, ``dletrec``, ``blet``, ``bletseq`` and ``bletrec`` macros.

---

*What does "metamagical" mean? To me, it means "going one level beyond magic". There is an ambiguity here: on the one hand, the word might mean "ultramagical" - magic of a higher order - yet on the other hand, the magical thing about magic is that what lies behind it is always nonmagical. That's metamagic for you!*
--Douglas R. Hofstadter, *On Self-Referential Sentences* (essay, 1981)

**New**:

- Alternative, haskelly ``let`` syntax ``let[((x, 2), (y, 3)) in x + y]`` and ``let[x + y, where((x, 2), (y, 3))]``
- Supported by all ``let`` forms: ``let``, ``letseq``, ``letrec``, ``let_syntax``, ``abbrev``
- When making just one binding, can now omit outer parentheses in ``let``: ``let(x, 1)[...]``, ``let[(x, 1) in ...]``, ``let[..., where(x, 1)]``
- ``unpythonic.misc.Box``: the classic rackety single-item mutable container
- Many small improvements to documentation

**Breaking changes**:

- New, perhaps more natural ``call_cc[]`` syntax for continuations, replaces earlier ``with bind[...]``
- Conditional continuation capture with ``call_cc[f() if p else None]``
- ``cc`` parameter now added implicitly, no need to declare explicitly unless actually needed (reduces visual noise in client code)
- Local variables in a ``do`` are now declared using macro-expr syntax ``local[x << 42]``, looks more macropythonic
- Silly ``(lambda)`` suffix removed from names of named lambdas (to detect them in client code, it's enough that ``isinstance(f, types.LambdaType)``)

---