Update readme and changelog for v0.9.0 changes (#526)

CHANGELOG.md

@@ -5,7 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.0] - 2024-05-10
+
+Previously, ALE implemented only a [Gym](https://github.com/openai/gym) based environment, however, as Gym is no longer maintained (last commit was 18 months ago). We have updated `ale-py` to use [Gymnasium](http://github.com/farama-Foundation/gymnasium) (a maintained fork of Gym) as the sole backend environment implementation. For more information on Gymnasium’s API, see their [introduction page](https://gymnasium.farama.org/main/introduction/basic_usage/).
+
+```python
+import gymnasium as gym
+import ale_py
+
+gym.register_envs(ale_py)  # this is unnecessary but prevents IDE complaining
+
+env = gym.make("ALE/Pong-v5", render_mode="human")
+
+obs, info = env.reset()
+episode_over = False
+while not episode_over:
+	action = policy(obs)  # replace with actual policy
+	obs, reward, terminated, truncated, info = env.step(action)
+	episode_over = terminated or truncated
+env.close()
+```
+
+An important change in this update is that the Atari ROMs are packaged within the PyPI installation such that users no longer require AutoROM or `ale-import-roms` for downloading or loading ROMs. This should significantly simplify installing Atari for users. For users that wish to load ROMs from an alternative folder, use the `ALE_ROM_DIR` system environment variable to specify a folder directory.
+
+Importantly, Gymnasium 1.0.0 removes a registration plugin system that ale-py utilises where atari environments would be registered behind the scene. As a result, projects will need to import `ale_py`, to register all the atari environments, before an atari environment can be created with `gymnasium.make`. For example, see below
+
+### Other changes
+- Added Python 3.12 support.
+- Replace interactive exit by sys.exit (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/498)
+- Fix C++ documentation example links(https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/501)
+- Add support for gcc 13 (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/503)
+- Unpin cmake dependency and remove wheel from build system (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/493)
+- Add missing imports for cstdint (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/486)
+- Allow installing without git (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/492)
+- Update to require `importlib-resources` for < 3.9  (https://github.com/Farama-Foundation/Arcade-Learning-Environment/pull/491)
 
 ## [0.8.1] - 2023-02-17
 

README.md

@@ -1,13 +1,12 @@
 The Arcade Learning Environment
 <a href="#the-arcade-learning-environment">
-  <img alt="Arcade Learning Environment" align="right" src="docs/static/ale.svg" width=75 />
+  <img alt="Arcade Learning Environment" align="right" width=75 src="https://raw.githubusercontent.com/Farama-Foundation/Arcade-Learning-Environment/master/docs/static/ale.svg" />
 </a>
 ===============================
 
-[![Continuous Integration](https://github.com/mgbellemare/Arcade-Learning-Environment/actions/workflows/ci.yml/badge.svg)](https://github.com/mgbellemare/Arcade-Learning-Environment/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/ale-py.svg)](https://badge.fury.io/py/ale-py)
 [![PyPI Version](https://img.shields.io/pypi/v/ale-py)](https://pypi.org/project/ale-py)
 
-
 **The Arcade Learning Environment (ALE) is a simple framework that allows researchers and hobbyists to develop AI agents for Atari 2600 games.**
 It is built on top of the Atari 2600 emulator [Stella](https://stella-emu.github.io) and separates the details of emulation from agent design.
 This [video](https://www.youtube.com/watch?v=nzUiEkasXZI) depicts over 50 games currently supported in the ALE.
@@ -19,20 +18,18 @@ Features
 --------
 
 - Object-oriented framework with support to add agents and games.
-- Emulation core uncoupled from rendering and sound generation modules for fast
-  emulation with minimal library dependencies.
-- Automatic extraction of game score and end-of-game signal for more than 100
-  Atari 2600 games.
+- Emulation core uncoupled from rendering and sound generation modules for fast emulation with minimal library dependencies.
+- Automatic extraction of game score and end-of-game signal for more than 100  Atari 2600 games.
 - Multi-platform code (compiled and tested under macOS, Windows, and several Linux distributions).
 - Python bindings through [pybind11](https://github.com/pybind/pybind11).
-- Native support for OpenAI Gym.
+- Native support for [Gymnasium](http://github.com/farama-Foundation/gymnasium), a maintained fork of OpenAI Gym.
 - Visualization tools.
+- Atari roms are packaged within the pip package
 
 Quick Start
 ===========
 
-The ALE currently supports three different interfaces: C++, Python, and OpenAI Gym.
-
+The ALE currently supports three different interfaces: C++, Python, and Gymnasium.
 
 Python
 ------
@@ -42,55 +39,39 @@ You simply need to install the `ale-py` package distributed via PyPI:
 ```shell
 pip install ale-py
 ```
-Note: Make sure you're using an up to date version of `pip` or the install may fail.
-
+Note: Make sure you're using an up-to-date version of `pip` or the installation may fail.
 
-You can now import the ALE in your Python projects with
+You can now import the ALE in your Python projects with providing a direct interface to Stella for interacting with games
 ```python
 from ale_py import ALEInterface
 
 ale = ALEInterface()
-```
-
-### ROM Management
-
-The ALE doesn't distribute ROMs but we do provide a couple tools for managing your ROMs. First is the command line tool `ale-import-roms`. You can simply specify a directory as the first argument to this tool and we'll import all supported ROMs by the ALE.
-
-```shell
-ale-import-roms roms/
-
-[SUPPORTED]       breakout   roms/breakout.bin
-[SUPPORTED]       freeway    roms/freeway.bin
+ale.loadROM("Breakout")
+ale.reset_game()
 
-[NOT SUPPORTED]              roms/custom.bin
-
-Imported 2/3 ROMs
-```
-Furthermore, Python packages can expose ROMs for discovery using the special `ale-py.roms` entry point. For more details check out the example [python-rom-package](./examples/python-rom-package).
-
-Once you've imported a supported ROM you can simply import the path from the `ale-py.roms` package and load the ROM in the ALE:
-```py
-from ale_py.roms import Breakout
-
-ale.loadROM(Breakout)
+reward = ale.act(0)  # noop
+screen_obs = ale.getScreenRGB()
 ```
 
-## OpenAI Gym
-
-Gym support is included in `ale-py`. Simply install  the Python package using the instructions above. You can also install `gym[atari]` which also installs `ale-py` with Gym.
+## Gymnasium
 
-As of Gym v0.20 and onwards all Atari environments are provided via `ale-py`. We do recommend using the new `v5` environments in the `ALE` namespace:
+For simplicity for installing ale-py with Gymnasium, `pip install "gymnasium[atari]"` shall install all necessary modules and ROMs. See Gymnasium [introductory page](https://gymnasium.farama.org/main/introduction/basic_usage/) for description of the API to interface with the environment.
 
 ```py
-import gym
+import gymnasium as gym
 
-env = gym.make('ALE/Breakout-v5')
-```
-The `v5` environments follow the latest methodology set out in [Revisiting the Arcade Learning Environment by Machado et al.](https://jair.org/index.php/jair/article/view/11182).
+env = gym.make('ALE/Breakout-v5', render_mode="human")  # remove render_mode in training
+obs, info = env.reset()
+episode_over = False
+while not episode_over:
+    action = policy(obs)  # to implement - use `env.action_space.sample()` for a random policy
+    obs, reward, terminated, truncated, info = env.step(action)
 
-The only major change difference from Gym's `AtariEnv` is that we'd recommend not using the `env.render()` method in favour of supplying the `render_mode` keyword argument during environment initialization. The `human` render mode will give you the advantage of: frame perfect rendering, audio support, and proper resolution scaling. For more information check out [docs/gym-interface.md](./docs/gym-interface.md).
+    episode_over = terminated or truncated
+env.close()
+```
 
-For more information on changes to the Atari environments in OpenAI Gym please check out [the following blog post](https://brosa.ca/blog/ale-release-v0.7).
+For all the environments available and their description, see [gymnasium atari page](https://gymnasium.farama.org/environments/atari/).
 
 C++
 ---

pyproject.toml

@@ -20,14 +20,19 @@ authors = [
   {name = "Michael Bowling"},
 ]
 maintainers = [
+  { name = "Farama Foundation", email = "contact@farama.org" },
   {name = "Jesse Farebrother", email = "jfarebro@cs.mcgill.ca"},
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Topic :: Scientific/Engineering",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
@@ -42,13 +47,13 @@ dynamic = ["version"]
 [project.optional-dependencies]
 test = [
   "pytest>=7.0",
-  "gymnasium==1.0.0a1",
+  "gymnasium>=1.0.0a1",
 ]
 
 [project.urls]
-homepage = "https://github.com/mgbellemare/Arcade-Learning-Environment"
-documentation = "https://github.com/mgbellemare/Arcade-Learning-Environment/tree/master/docs"
-changelog = "https://github.com/mgbellemare/Arcade-Learning-Environment/blob/master/CHANGELOG.md"
+homepage = "https://github.com/Farama-Foundation/Arcade-Learning-Environment"
+documentation = "https://github.com/Farama-Foundation/Arcade-Learning-Environment/tree/master/docs"
+changelog = "https://github.com/Farama-Foundation/Arcade-Learning-Environment/blob/master/CHANGELOG.md"
 
 [tool.setuptools]
 packages = [