Hy

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

Supports Python 3.8 – Python 3.13

See also the announcement post for this release (to be linked).

Bug Fixes
------------------------------
* Fixed a crash on Python 3.12.6.
* Keyword objects can now be compared to each other with `<` etc.
* The order of evaluation in multi-item `with`\s now matches that of
nested one-item `with`\s.
* Fixed a bug in which the REPL misinterpreted the symbol `pass`.

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

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

Other Breaking Changes
------------------------------
* `import` and `require` no longer need outer brackets.
`(import [foo [bar]])` is now `(import foo [bar])`
and `(import [foo :as baz])` is now `(import foo :as baz)`.
To import all names from a module, use `(import foo *)`.
* Lots of objects (listed below) have been spun off to a new package
called `Hyrule`_, from which you can `import` or `require` them.
Thus Hy now brings only the `hy` module and a limited set of core
macros into scope automatically.

* Functions: `butlast`, `coll?`, `constantly`, `dec`, `destructure`, `distinct`, `drop-last`, `end-sequence`, `flatten`, `inc`, `macroexpand-all`, `parse-args`, `pformat`, `postwalk`, `pp`, `pprint`, `prewalk`, `readable?`, `recursive?`, `rest`, `saferepr`, `walk`
* Classes: `PrettyPrinter`, `Sequence`
* Macros: `%`, `:`, `->`, `->>`, `ap-dotimes`, `ap-each`, `ap-each-while`, `ap-filter`, `ap-first`, `ap-if`, `ap-last`, `ap-map`, `ap-map-when`, `ap-reduce`, `ap-reject`, `as->`, `assoc`, `cfor`, `comment`, `defmacro!`, `defmacro/g!`, `defmain`, `defn+`, `defn/a+`, `defseq`, `dict=:`, `do-n`, `doto`, `fn+`, `fn/a+`, `ifp`, `let+`, `lif`, `list-n`, `loop`, `ncut`, `of`, `profile/calls`, `profile/cpu`, `seq`, `setv+`, `smacrolet`, `unless`, `with-gensyms`

* Functions that provide first-class Python operators, such as `+`
in constructs like `(reduce + xs)`, are no longer brought
into scope automatically. Say `(import hy.pyops *)` to get them.
* Hy scoping rules more closely follow Python scoping in certain edge
cases.
* `let` is now a core macro with somewhat different semantics. In
particular, definition-like core macros (`defn`, `defclass`,
`import`) now introduce new names that shadow corresponding
`let`-bound names and persist outside the body of the `let`.
* The constructors of `String` and `FString` now check that the input
would be syntactically legal as a literal.
* `hy.extra.reserved` has been renamed to `hy.reserved`.

New Features
------------------------------
* `hy.repr` now supports several more standard types.
* The attribute access macro `.` now allows method calls. For example,
`(. x (f a))` is equivalent to `(x.f a)`.
* `hy.as-model` checks for self-references in its argument.
* New function `hy.model_patterns.keepsym`.

Bug Fixes
------------------------------
* In comprehension forms other than `for`, assignments (other than
`:setv` and loop clauses) are now always visible in the surrounding
scope.
* `match` now only evaluates the subject once.
* `let` will no longer re-evaluate the default arguments of a
function it's used in.
* `hy.repr` now properly formats bracket strings.
* The `repr` and `str` of string models now include `brackets` if
necessary.
* When standard output can't accommodate Unicode, `hy2py` now crashes
instead of emitting incorrect Python code.
* Fixed a bug with self-requiring files on Windows.
* Improved error messages for illegal uses of `finally` and `else`.

.. _Hyrule: https://github.com/hylang/hyrule

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

Bug Fixes
------------------------------
* Fixed a dependency-management bug that prevented installation of Hy
from a wheel on Pythons < 3.9.

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

Removals
------------------------------
* All reimplementations of functions in the package `Toolz`_ have been
removed. Import these from Toolz (or `CyToolz`_) instead. Beware that
the Toolz functions are not all drop-in replacements for the old Hy
functions; e.g., `partition` has a different order of parameters.

* `complement`, `compose` (formerly `comp` in Hy), `drop`, `first`,
`identity`, `interleave`, `interpose`, `iterate`, `juxt`, `last`,
`merge-with`, `nth`, `partition`, `second`, `take-nth`, `take`

* All aliases of objects in Python's standard library have been removed.
Import these objects explicitly instead.

* From `itertools`: `accumulate`, `chain`,
`combinations-with-replacement` (formerly `multicombinations` in
Hy), `combinations`, `compress`, `count`, `cycle`, `dropwhile`
(formerly `drop-while`), `filterfalse` (formerly `remove`),
`groupby` (formerly `group-by`), `islice`, `permutations`,
`product`, `repeat`, `starmap` (formerly `*map`), `takewhile`
(formerly `take-while`), `tee`, `zip-longest`
* From `functools`: `reduce`
* From `fractions`: `Fraction` (formerly `fraction`)

* The following core predicate functions have been removed. Use
`isinstance` etc. instead.

* `empty?`, `even?`, `every?`, `float?`, `integer-char?`,
`integer?`, `iterable?`, `iterator?`, `keyword?`, `list?`, `neg?`,
`none?`, `numeric?`, `odd?`, `pos?`, `some`, `string?`, `symbol?`,
`tuple?`, `zero?`

* Several other core functions and macros have been removed:

* `keyword`: Use `(hy.models.Keyword (hy.unmangle …))` instead.
* `repeatedly`: Use `toolz.iterate` instead.
* `if-not`: Use `(if (not …) …)` instead.
* `lif-not`: Use `(lif (not …) …)` instead.
* `macro-error`: Use `raise` instead.
* `calling-module`: Now internal to Hy.
* `calling-module-name`: Now internal to Hy.

Other Breaking Changes
------------------------------
* `if` no longer allows more than three arguments. Use `cond` instead.
* `cut` with exactly two arguments (the object to be cut and the
index) now works like Python slicing syntax and the `slice`
function: `(cut x n)` gets the first `n` elements instead of
everything after the first `n`.
* In `defn`, the return-value annotation, if any, is now placed before
the function name instead of after.
* Python reserved words are no longer allowed as parameter names, nor
as keywords in keyword function calls.
* Hy model objects are no longer equal to ordinary Python values.
For example, `(!= 1 '1)`. You can promote values to models with
`hy.as-model` before making such a check.
* The following functions are now called as attributes of the `hy` module:

* `hy.disassemble`, `hy.gensym`, `hy.macroexpand`,
`hy.macroexpand-1`, `hy.repr` (formerly
`hy.contrib.hy-repr.hy-repr`), `hy.repr-register` (formerly
`hy.contrib.hy-repr.hy-repr-register`)

* `cmp` has been renamed to `chainc`.
* `defclass` no longer automatically adds `None` to the end of
`__init__` method definitions.
* All special forms have been replaced with macros. This won't affect
most preexisting code, but it does mean that user-defined macros can
now shadow names like `setv`.
* `hy.repr` no longer uses the registered method of a supertype.
* The constructors of `Symbol` and `Keyword` now check that the input
would be syntactically legal.
* Attempting to call a core macro not implemented on the current
version of Python is now an error.
* `hy.extra.reserved.special` has been replaced with
`hy.extra.reserved.macros`.

New Features
------------------------------
* `hy-repr` is now the default REPL output function.
* The command `python -m hy` now works the same as `hy`.
* New function `hy.as-model`.
* New macro `match` (Python 3.10 only).
* `annotate` is now a user-visible macro.

Bug Fixes
------------------------------
* Fixed issues with newer prereleases of Python 3.10.
* The REPL now properly displays `SyntaxError`\s.
* Fixed a bug in `pprint` in which `width` was ignored.
* Corrected `repr` and `hy.repr` for f-strings.
* `--spy` and `--repl-output-fn` can now overwrite `HYSTARTUP` values.

.. _Toolz: https://toolz.readthedocs.io
.. _CyToolz: https://github.com/pytoolz/cytoolz

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

Removals
------------------------------
* The core function `name` has been removed.
Use `unmangle` or the `name` attribute of keyword objects instead.
* `deftag` has been removed. Instead of `(deftag foo …)`,
say `(defmacro "foo" …)`.
* `doc` has been removed. Instead of `doc `, say `(doc "")`.
* `__tags__` has been removed. Tag macros are now tracked in
`__macros__`.

Other Breaking Changes
------------------------------
* Lambda lists (function parameter lists) have been simplified.
`&optional` is gone, `&args` is `*`, `&kwargs` is `**`, and
`&kwonly` is `*`. Thus, `[a &optional b [c 3] &rest args &kwargs
kwargs]` is now `[a [b None] [c 3] * args ** kwargs]`.
* Hy models have been renamed to remove "Hy", and are no longer
automatically brought into scope. Thus, `HyList` is now
`hy.models.List`.
* `eval` is no longer automatically brought into scope. Call it as
`hy.eval` (or import it explicitly).
* Calling a keyword object now does a string lookup, instead of a
keyword-object lookup. Thus, `(:key obj)` is equivalent to `(get
obj (mangle (. :key name)))`.
* To require a tag macro `foo`, instead of `(require [module [foo]])`,
you must now say `(require [module ["foo"]])`.
* Mangling no longer converts leading hyphens to underscores, and
unmangling no longer converts leading underscores to hyphens.
* F-strings now have their own model type, and store their code parts
as models instead of strings.

New Features
------------------------------
* Python 3.10 is now supported.
* Lambda lists now support positional-only arguments.
* F-strings now support `=` syntax per Python.
* `with` now supports unnamed context managers.
* `defmacro` and `require` can now take macro names as string
literals.
* New standard macros `do-n`, `list-n`, and `cfor`.
* The location of the REPL history file can now be set with the
environment variable `HY_HISTORY`.
* REPL initialization scripts are now supported with the envrionment
variable `HYSTARTUP`.
* The module `hy.extra.reserved` has a new function `special`.
* New module `hy.contrib.destructure` for Clojure-style destructuring.
* New module `hy.contrib.slicing` for multi-index sequence slicing.

Bug Fixes
------------------------------
* Fixed the identifier `J` being incorrectly parsed as a complex
number.
* Attempts to assign to constants are now more reliably detected.
* Fixed a bug where AST nodes from macro expansion did not properly
receive source locations.
* Fixed `doc` sometimes failing to find core macros.
* `doc` now works with names that need mangling.
* Fixed bugs with `require` of names that need mangling.
* Fixed a compiler crash from trying to use `..` as an operator.
* Fixed namespace pollution caused by automatic imports of Hy builtins
and macros.
* `require` now works with relative imports and can name modules as
members, as in `(require [hy.contrib [walk]])`.
* Fixed error handling for illegal macro names.
* Fixed `hyc` and `hy2py` not finding relative imports.
* Fixed `hy.contrib.walk.smacrolet` requiring a module name.

Misc. Improvements
------------------------------
* The library `astor` is no longer required on Pythons ≥ 3.9.

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

Removals
------------------------------
* `hy.disassemble` has been removed.
* `(defn/a …)` is now `(defn :async …)`.
* `(fn/a …)` is now `(fn :async …)`.
* `(with/a […] …)` is now `(with [:async …] …)`.

* As with `for`, `:async` must precede each name to be bound
asynchronously, because you can mix synchronous and asynchronous
types.

* `(yield-from …)` is now `(yield :from …)`.

New Features
------------------------------
* You can now set `repl-ps1` and `repl-ps2` in your `HYSTARTUP` to customize
`sys.ps1` and `sys.ps2` for the Hy REPL.

Bug Fixes
------------------------------
* Tracebacks now point to the correct code in more cases.
* `help` should no longer crash when objects are missing docstrings.
* `hy -i < script.hy` now executes `script.hy` inside the REPL environment,
like Python.