Hy

==============================

**Warning**: Hy 0.17.x will be the last Hy versions to support Python 2,
and we expect 0.17.0 to be the only release in this line. By the time
0.18.0 is released (in 2020, after CPython 2 has ceased being developed),
Hy will only support Python 3.

Removals
------------------------------
* Python 3.4 is no longer supported.

New Features
------------------------------
* Python 3.8 is now supported.
* Format strings with embedded Hy code (e.g., `f"The sum is {(+ x y)}"`)
are now supported, even on Pythons earlier than 3.6.
* Added a special form `setx` to create Python 3.8 assignment expressions.
* Added new core functions `list?` and `tuple`.
* Gensyms now have a simpler format that's more concise when
mangled (e.g., `_hyx_XsemicolonXfooXvertical_lineX1235` is now
`_hyx_fooXUffffX1`).

Bug Fixes
------------------------------
* Fixed a crash caused by errors creating temporary files during
bytecode compilation.

==============================

Removals
------------------------------
* Empty expressions (`()`) are no longer legal at the top level.

New Features
------------------------------
* `eval` / `hy_eval` and `hy_compile` now accept an optional `compiler`
argument that enables the use of an existing `HyASTCompiler` instance.
* Keyword objects (not just literal keywords) can be called, as
shorthand for `(get obj :key)`, and they accept a default value
as a second argument.
* Minimal macro expansion namespacing has been implemented. As a result,
external macros no longer have to `require` their own macro
dependencies.
* Macros and tags now reside in module-level `__macros__` and `__tags__`
attributes.

Bug Fixes
------------------------------
* Cleaned up syntax and compiler errors.
* You can now call `defmain` with an empty lambda list.
* `require` now compiles to Python AST.
* Fixed circular `require`\s.
* Fixed module reloading.
* Fixed circular imports.
* Fixed errors from `from __future__ import ...` statements and missing
Hy module docstrings caused by automatic importing of Hy builtins.
* Fixed `__main__` file execution.
* Fixed bugs in the handling of unpacking forms in method calls and
attribute access.
* Fixed crashes on Windows when calling `hy-repr` on date and time
objects.
* Fixed a crash in `mangle` for some pathological inputs.
* Fixed incorrect mangling of some characters at low code points.
* Fixed a crash on certain versions of Python 2 due to changes in the
standard module `tokenize`.

==============================

Removals
------------------------------
* Dotted lists, `HyCons`, `cons`, `cons?`, and `list*` have been
removed. These were redundant with Python's built-in data structures
and Hy's most common model types (`HyExpression`, `HyList`, etc.).
* `&key` is no longer special in lambda lists. Use `&optional` instead.
* Lambda lists can no longer unpack tuples.
* `ap-pipe` and `ap-compose` have been removed. Use threading macros and
`comp` instead.
* `for/a` has been removed. Use `(for [:async ...] ...)` instead.
* `(except)` is no longer allowed. Use `(except [])` instead.
* `(import [foo])` is no longer allowed. Use `(import foo)` instead.

Other Breaking Changes
------------------------------
* `HyExpression`, `HyDict`, and `HySet` no longer inherit from `HyList`.
This means you can no longer use alternative punctuation in place of
square brackets in special forms (e.g. `(fn (x) ...)` instead of
the standard `(fn [x] ...)`).
* Mangling rules have been overhauled; now, mangled names are
always legal Python identifiers.
* `_` and `-` are now equivalent, even as single-character names.

* The REPL history variable `_` is now `*1`.

* Non-shadow unary `=`, `is`, `<`, etc. now evaluate their argument
instead of ignoring it.
* `list-comp`, `set-comp`, `dict-comp`, and `genexpr` have been replaced
by `lfor`, `sfor`, `dfor`, and `gfor`, respectively, which use a new
syntax and have additional features. All Python comprehensions can now
be written in Hy.
* `&`-parameters in lambda lists must now appear in the same order that
Python expects.
* Literal keywords now evaluate to themselves, and `HyKeyword` no longer
inherits from a Python string type
* `HySymbol` no longer inherits from `HyString`.

New Features
------------------------------
* Python 3.7 is now supported.
* `while` and `for` are allowed to have empty bodies.
* `for` supports the various new clause types offered by `lfor`.
* `defclass` in Python 3 supports specifying metaclasses and other
keyword arguments.
* Added `mangle` and `unmangle` as core functions.
* Added more REPL history variables: `*2` and `*3`.
* Added a REPL variable holding the last exception: `*e`.
* Added a command-line option `-E` per CPython.
* Added a new module `hy.model_patterns`.

Bug Fixes
------------------------------
* `hy2py` should now output legal Python code equivalent to the input Hy
code in all cases.
* Fixed `(return)` so it can exit a Python 2 generator.
* Fixed a case where `->` and `->>` duplicated an argument.
* Fixed bugs that caused `defclass` to drop statements or crash.
* Fixed a REPL crash caused by illegal backslash escapes.
* `NaN` can no longer create an infinite loop during macro-expansion.
* Fixed a bug that caused `try` to drop expressions.
* The compiler now properly recognizes `unquote-splice`.
* Trying to import a dotted name is now a syntax error, as in Python.
* `defmacro!` now allows optional arguments.
* Fixed handling of variables that are bound multiple times in a single
`let`.

Misc. Improvements
----------------------------
* `hy-repr` uses registered functions instead of methods.
* `hy-repr` supports more standard types.
* `macroexpand-all` will now expand macros introduced by a `require` in the body of a macro.

==============================

Removals
------------------------------
* Python 3.3 is no longer supported
* `def` is gone; use `setv` instead
* `apply` is gone; use the new `*` and `**` syntax instead
* `yield-from` is no longer supported under Python 2
* Periods are no longer allowed in keywords
* Numeric literals can no longer begin with a comma or underscore
* Literal `Inf`\s and `NaN`\s must now be capitalized like that

Other Breaking Changes
------------------------------
* Single-character "sharp macros" are now "tag macros", which can have
longer names
* `xi` from `hy.extra.anaphoric` is now a tag macro `%`
* `eval` is now a function instead of a special form

New Features
------------------------------
* The compiler now automatically promotes values to Hy model objects
as necessary, so you can write ``(eval `(+ 1 ~n))`` instead of
``(eval `(+ 1 ~(HyInteger n)))``
* `return` has been implemented as a special form
* Added a form of string literal called "bracket strings" delimited by
`[FOO[` and `]FOO]`, where `FOO` is customizable
* Added support for PEP 492 (`async` and `await`) with `fn/a`, `defn/a`,
`with/a`, and `for/a`
* Added Python-style unpacking operators `*` and `**` (e.g.,
`(f * args ** kwargs)`)
* Added a macro `comment`
* Added EDN `_` syntax to discard the next term
* `while` loops may now contain an `else` clause, like `for` loops
* `%` works on any expression and has a new `&kwargs` parameter `%**`
* Added a macro `doc` and a tag macro `doc`
* `get` is available as a function
* `~` (`unquote-splice`) form now accepts any false value as empty

Bug Fixes
------------------------------
* Relative imports (PEP 328) are now allowed
* Numeric literals are no longer parsed as symbols when followed by a dot
and a symbol
* Hy now respects the environment variable `PYTHONDONTWRITEBYTECODE`
* String literals should no longer be interpreted as special forms or macros
* Tag macros (née sharp macros) whose names begin with `!` are no longer
mistaken for shebang lines
* Fixed a bug where REPL history wasn't saved if you quit the REPL with
`(quit)` or `(exit)`
* `exec` now works under Python 2
* No TypeError from multi-arity `defn` returning values evaluating to `None`
* `try` forms are now possible in `defmacro` and `deftag`
* Multiple expressions are now allowed in `try`
* Fixed a crash when `macroexpand`\ing a macro with a named import
* Fixed a crash when `with` suppresses an exception. `with` now returns
`None` in this case.
* Fixed a crash when `--repl-output-fn` raises an exception
* Fixed a crash when `HyTypeError` was raised with objects that had no
source position
* `assoc` now evaluates its arguments only once each
* Multiple expressions are now allowed in the `else` clause of
a `for` loop
* `else` clauses in `for` and `while` are recognized more reliably
* Statements in the condition of a `while` loop are repeated properly
* Argument destructuring no longer interferes with function docstrings
* Nullary `yield-from` is now a syntax error
* `break` and `continue` now raise an error when given arguments
instead of silently ignoring them

Misc. Improvements
------------------------------
* `read`, `read_str`, and `eval` are exposed and documented as top-level
functions in the `hy` module
* An experimental `let` macro has been added to `hy.contrib.walk`

==============================

Bug Fixes
------------------------------
* Changed setup.py to require astor 0.5, since 0.6 isn't
backwards-compatible.

==============================

Language Changes
------------------------------
* Pythons 2.6, 3.0, 3.1, and 3.2 are no longer supported
* `let` has been removed. Python's scoping rules do not make a proper
implementation of it possible. Use `setv` instead.
* `lambda` has been removed, but `fn` now does exactly what `lambda` did
* `defreader` has been renamed to `defsharp`; what were previously called
"reader macros", which were never true reader macros, are now called
"sharp macros"
* `try` now enforces the usual Python order for its elements (`else` must
follow all `except`\s, and `finally` must come last). This is only a
syntactic change; the elements were already run in Python order even when
defined out of order.
* `try` now requires an `except` or `finally` clause, as in Python
* Importing or executing a Hy file automatically byte-compiles it, or loads
a byte-compiled version if it exists and is up to date. This brings big
speed boosts, even for one-liners, because Hy no longer needs to recompile
its standard library for every startup.
* Added bytestring literals, which create `bytes` objects under Python 3
and `str` objects under Python 2
* Commas and underscores are allowed in numeric literals
* Many more operators (e.g., `**`, `//`, `not`, `in`) can be used
as first-class functions
* The semantics of binary operators when applied to fewer or more
than two arguments have been made more logical
* `(** a b c d)` is now equivalent to `(** a (** b (** c d)))`,
not `(** (** (** a b) c) d)`
* `setv` always returns `None`
* When a `try` form executes an `else` clause, the return value for the
`try` form is taken from `else` instead of the `try` body. For example,
`(try 1 (except [ValueError] 2) (else 3))` returns `3`.
* `xor`: If exactly one argument is true, return it
* `hy.core.reserved` is now `hy.extra.reserved`
* `cond` now supports single argument branches

Bug Fixes
------------------------------
* All shadowed operators have the same arities as real operators
* Shadowed comparison operators now use `and` instead of `&`
for chained comparisons
* `partition` no longer prematurely exhausts input iterators
* `read` and `read-str` no longer raise an error when the input
parses to a false value (e.g., the empty string)
* A `yield` inside of a `with` statement will properly suppress implicit
returns
* `setv` no longer unnecessarily tries to get attributes
* `loop` no longer replaces string literals equal to "recur"
* The REPL now prints the correct value of `do` and `try` forms
* Fixed a crash when tokenizing a single quote followed by whitespace

Misc. Improvements
------------------------------
* New contrib module `hy-repr`
* Added a command-line option `--repl-output-fn`