Merge pull request #58 from pythonarcade/development

Version 2.1.0

Author: Cleptomania

.readthedocs.yml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements: 
+        - docs

CHANGELOG.md

@@ -4,6 +4,16 @@ 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/),
 
+## [2.1.0] - 2022-08-02
+
+This is largely a compatibility update to work with the latest version of Tiled. This version represents the first version of pytiled-parser that is compatible with the formats from Tiled 1.9. Previous versions do not work with maps or tilesets of either JSON or TMX formats from Tiled 1.9 or higher, if you need to use Tiled 1.9+ with an older version of Tiled, you will need to use Tiled's ability to save the map in compatibility mode.
+
+This update does introduce a slight API breaking change, but is unlikely to really cause any problems. The `type` attribute has been removed from the `TiledObject` class as well as the `Tile` class. It has been replaced with the `class_` attribute. This is in keeping with following Tiled's own API as closely as possible. There shouldn't really be any functional difference here, in most cases it has just been re-named. For more information on this change, you can reference the [Tiled JSON format changelog](https://doc.mapeditor.org/en/stable/reference/json-map-format/#changelog).
+
+It is important to note, that this update does not add support for new features introduced in Tiled 1.9(and in fact, we are still missing support for some features from 1.8). This update is primarily to ensure that maps using the base feature set we have had support for will continue to work with the same supported featureset on Tiled 1.9. Support for the new features is something we would like to achieve, but we did not want to hold back general compatibility for it.
+
+Outside of that, all other changes are to the internal parsers and do not effect usage/implementation of pytiled-parser.
+
 ## [2.0.1] - 2021-12-21
 
 Someone, not naming any names, forgot to put `__init__.py` files in some packages, and caused imports to break when installed via a `.whl` and not an editable source install. This just fixes that problem.

README.md

@@ -1,27 +1,74 @@
-# PyTiled Parser
+# pytiled-parser
 
-PyTiled Parser is a Python Library for parsing JSON formatted
-[Tiled Map Editor](https://www.mapeditor.org/) maps and tilesets to be used as maps and levels for 2D top-down (orthogonal, hexogonal, or isometric) or side-scrolling games in a strictly typed fashion.
+PyTiled Parser is a Python Library for parsing [Tiled Map Editor](https://www.mapeditor.org/) maps and tilesets to be used as maps and levels for 2D top-down (orthogonal, hexogonal, or isometric) or side-scrolling games in a strictly typed fashion.
 
-PyTiled Parser is not tied to any particular graphics library, and can be used
-with [Arcade](http://arcade.academy), 
-[Pyglet](https://pyglet.readthedocs.io/en/pyglet-1.3-maintenance/), 
-[Pygame](https://www.pygame.org/news), etc. 
+PyTiled Parser is not tied to any particular graphics library or game engine. It parses map files and returns arbitrary Python types(like `Path` objects for image files rather than a `Sprite` from any particular engine). This means it can be used to aide in implementing Tiled support into a wide variety of tools.
 
-* Documentation available at: https://pytiled-parser.readthedocs.io/
-* GitHub project at: https://github.com/Beefy-Swain/pytiled_parser
-* PiPy: https://pypi.org/project/pytiled-parser/
+- Documentation available at: https://pytiled-parser.readthedocs.io/
+- GitHub project at: https://github.com/pythonarcade/pytiled_parser
+- PyPi: https://pypi.org/project/pytiled-parser/
 
-The [Arcade](http://arcade.academy) library has 
-[supporting code](http://arcade.academy/arcade.html#module-arcade.tilemap) to 
-integrate PyTiled with that 2D libary, and 
-[example code](http://arcade.academy/examples/index.html#tmx-files-tiled-map-editor) showing its use.
+The [Arcade](https://api.arcade.academy) library has
+[supporting code](https://api.arcade.academy/en/latest/api/tilemap.html) to
+integrate PyTiled Parser and [example code](https://api.arcade.academy/en/latest/examples/index.html#using-tiled-map-editor-to-create-maps) showing its use.
 
-Original module by [Beefy-Swain](https://github.com/Beefy-Swain). 
-Significant contributions from [pvcraven](https://github.com/pvcraven) and [Cleptomania](https://github.com/Cleptomania).
+## Installation
+
+Simply install with pip:
+
+```
+pip install pytiled-parser
+```
+
+## Loading a Map
+
+**NOTE:** All map paths should ideally be `Path` objects from Python's `pathlib` module. However a string will work in many cases.
+
+```python
+from pathlib import Path
+
+import pytiled_parser
+
+map_file = Path("assets/maps/my_map.tmx")
+my_map = pytiled_parser.parse_map(map_file)
+```
+
+In order to fully understand the pytiled-parser API, it is suggested that you have a solid understanding of the [Tiled Map Editor](https://doc.mapeditor.org/en/stable/), and it's [JSON format](https://doc.mapeditor.org/en/stable/reference/json-map-format/). An effort was made to keep the API that pytiled-parser provides as close as possible with the JSON format directly. Only small variations are made at certain points for ease of use with integrating to a game or engine.
+
+## Working With Layers
+
+Layers are loaded as an ordered list of `Layer` objects within the map. They can be accessed via the `layers` attribute of a map. There has been debate about wether or not these should be loaded in as a Dictionary, with the keys being the name of the layer. The decision was ultimately made to leave them as a list, as there is no guarantee, and beyond that is considered acceptable use to have duplicate layer names in Tiled.
+
+Thus the decision to allow duplicate layer names is up to the implementation, as an example, [Arcade](https://arcade.academy) does not allow duplicate layer names, as it re-roganizes layers into dictionaries based on the name.
 
 ## Development
-To develop pytiled parser, clone the repo, create a `venv` using a supported Python version, and activate it. Then install the package as well as all testing dependencies with the command `python -m pip install -e ".[tests]"`.
+
+To develop pytiled parser, clone the repo, create a `venv` using a supported Python version, and activate it. Then install the package as well as all testing, linting, and formatting dependencies with the command `python -m pip install -e ".[dev]"`.
+
+### Linting and Formatting
+
+flake8, mypy, black, and isort should all be used during development. These should ideally all pass before committing. Some work is under way to have a pre-commit hook for these or do checks in CI.
 
 ### Testing
-Run `pytest --cov=pytiled_parser` to run the test harness and report coverage.
+
+Run `pytest --cov=pytiled_parser` to run the test harness and report coverage.
+
+### Docs
+
+Install Docs dependencies with the command `python -m pip install ".[docs]"`
+
+To serve the docs locally:
+
+```
+mkdocs serve
+```
+
+They can then be accessed on http://localhost:8000
+
+## Credits
+
+Original module created by [Benjamin Kirkbride](https://github.com/benjamin-kirkbride).
+
+Currently maintained by [Cleptomania](https://github.com/cleptomania)
+
+Special thanks for contributions from [pvcraven](https://github.com/pvcraven) and the contributors that create Tiled, without which this library wouldn't exist.

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/api/common_types.rst

@@ -0,0 +1,24 @@
+.. _common_types_api:
+Common Types
+============
+
+This module provides some common types used throughout PyTiled Parser. These are all just NamedTuple 
+classes provided to make sets of data more clear. As such they can be subscripted like a normal tuple
+to get the same values, or you can reference them by name. The values shown here are in the order they
+will be in the final tuple.
+
+
+Color
+^^^^^
+
+.. autoclass:: pytiled_parser.common_types.Color
+
+OrderedPair
+^^^^^^^^^^^
+
+.. autoclass:: pytiled_parser.common_types.OrderedPair
+
+Size
+^^^^
+
+.. autoclass:: pytiled_parser.common_types.Size

docs/api/index.rst

@@ -0,0 +1,26 @@
+.. _api:
+API Reference
+=============
+
+This page documents the Application Programming Interface (API) for the PyTiled Parser library.
+
+Throughout the API documentation you will see links labeled both TMX Reference and JSON Reference.
+These links go to the official Tiled documentation for that specific type. Sometimes there is not a
+one to one mapping, so it may lead to the closest thing in the Tiled format.
+
+At some points certain classes modules may have links to other parts of the Tiled documentation which
+cover some of the concepts surrounding that module and it's usage within Tiled.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: PyTiled Parser
+
+    parser
+    common_types
+    properties
+    tileset
+    layer
+    objects
+    map
+    wang_set
+    world

docs/api/layer.rst

@@ -0,0 +1,48 @@
+.. _layer_api:
+Layer
+=====
+
+This module provides classes for all layer types
+
+There is the base Layer class, which TileLayer, ObjectLayer, ImageLayer, 
+and LayerGroup all derive from. The base Layer class is never directly used,
+and serves only as an abstract base for common elements between all types.
+
+For more information about Layers, see `Tiled's Manual <https://doc.mapeditor.org/en/stable/manual/layers/>`_
+
+
+Layer
+^^^^^
+
+.. autoclass:: pytiled_parser.layer.Layer
+    :members:
+
+TileLayer
+^^^^^^^^^
+
+.. autoclass:: pytiled_parser.layer.TileLayer
+    :members:
+
+Chunk
+^^^^^
+
+.. autoclass:: pytiled_parser.layer.Chunk
+    :members:
+
+ObjectLayer
+^^^^^^^^^^^
+
+.. autoclass:: pytiled_parser.layer.ObjectLayer
+    :members:
+
+ImageLayer
+^^^^^^^^^^
+
+.. autoclass:: pytiled_parser.layer.ImageLayer
+    :members:
+
+LayerGroup
+^^^^^^^^^^
+
+.. autoclass:: pytiled_parser.layer.LayerGroup
+    :members:

docs/api/map.rst

@@ -0,0 +1,10 @@
+.. _map_api:
+Map
+===
+
+This module provides the primary TiledMap class which represents a single map from Tiled.
+
+TiledMap
+^^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_map.TiledMap

docs/api/objects.rst

@@ -0,0 +1,59 @@
+.. _objects_api:
+Objects
+=======
+
+This module provides classes for all of the Tiled Object types.
+
+There is the base TiledObject class, which all of the actual object types inherit from.
+The base TiledObject class is never directly used, and serves only as an abstract base
+for common elements between all types.
+
+Some objects have no extra attributes over the base class, they exist as different classes anyways
+to denote the type of object, so that an implementation can load it in accordingly. For example, an
+Ellipse and a Point have no differing attributes from the base class, but obviously need to be handled
+very differently.
+
+For more information about objects, see `Tiled's Manual <https://doc.mapeditor.org/en/stable/manual/objects/>`_
+
+Also see the `TMX Reference <https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#object>`_
+and `JSON Reference <https://doc.mapeditor.org/en/stable/reference/json-map-format/#object>`_
+
+TiledObject
+^^^^^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.TiledObject
+
+Ellipse
+^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Ellipse
+
+Point
+^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Point
+
+Polygon
+^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Polygon
+
+Polyline
+^^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Polyline
+
+Rectangle
+^^^^^^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Rectangle
+
+Text
+^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Text
+
+Tile
+^^^^
+
+.. autoclass:: pytiled_parser.tiled_object.Tile

docs/api/parser.rst

@@ -0,0 +1,17 @@
+.. _parser_api:
+Parser
+======
+
+This module exposes the actual parsing functions. If you are creating an implementation, this is
+what you will actually pass a file to and receive back a PyTiled Parser Map or World class depending
+on what you're parsing.
+
+pytiled_parser.parse_map
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: pytiled_parser.parse_map
+
+pytiled_parser.parse_world
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: pytiled_parser.parse_world

docs/api/properties.rst

@@ -0,0 +1,27 @@
+.. _properties_api:
+Properties
+==========
+
+This module provides some common types used throughout PyTiled Parser. These are all just NamedTuple 
+classes provided to make sets of data more clear. As such they can be subscripted like a normal tuple
+to get the same values, or you can reference them by name. The values shown here are in the order they
+will be in the final tuple.
+
+Properties do not have a special class or anything associated with them. They are simply type aliases for
+built-in Python types.
+
+pytiled_parser.Property
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pytiled_parser.Property`` type is a Union of the `float`, `str`, and `bool` built-in types, as well as
+`Path` class from pathlib, and the `pytiled_parser.Color` common type.
+
+A property may be any one of these types.
+
+pytiled_parser.Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pytiled_parser.Properties`` type is a Dictionary mapping of `str` to `pytiled_parser.Property` objects.
+
+When the map is parsed, all properties will be loaded in as a Property, and stored in a Properties dictionary
+with the name being it's key in the dictionary.