Merge pull request #479 from hugovk/replace-readme-rst-md

ultrajson · Sep 20, 2021 · c0fc29b · c0fc29b
2 parents 1dda667 + d66342b
commit c0fc29b
Show file tree

Hide file tree

Showing 5 changed files with 140 additions and 202 deletions.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,12 +1 @@
-recursive-include deps *
-
-include README.rst
-include MANIFEST.in
-include LICENSE.txt
-include setup.py
-include tests/tests.py
-include tests/sample.json
-include lib/*.c
-include lib/*.h
-include python/*.c
-include python/*.h
+include python/version.h
diff --git a/README.md b/README.md
@@ -0,0 +1,126 @@
+# UltraJSON
+
+[![PyPI version](https://img.shields.io/pypi/v/ujson.svg?logo=pypi&logoColor=FFE873)](https://pypi.org/project/ujson)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/ujson.svg?logo=python&logoColor=FFE873)](https://pypi.org/project/ujson)
+[![PyPI downloads](https://img.shields.io/pypi/dm/ujson.svg)](https://pypistats.org/packages/ujson)
+[![GitHub Actions status](https://github.com/ultrajson/ultrajson/workflows/Test/badge.svg)](https://github.com/ultrajson/ultrajson/actions)
+[![Travis CI status](https://travis-ci.com/ultrajson/ultrajson.svg?branch=main)](https://travis-ci.com/ultrajson/ultrajson)
+[![codecov](https://codecov.io/gh/ultrajson/ultrajson/branch/main/graph/badge.svg)](https://codecov.io/gh/ultrajson/ultrajson)
+[![DOI](https://zenodo.org/badge/1418941.svg)](https://zenodo.org/badge/latestdoi/1418941)
+[![Code style: Black](https://img.shields.io/badge/code%20style-Black-000000.svg)](https://github.com/psf/black)
+
+UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for
+Python 3.6+.
+
+Install with pip:
+
+```sh
+python -m pip install ujson
+```
+
+## Usage
+
+May be used as a drop in replacement for most other JSON parsers for Python:
+
+```pycon
+>>> import ujson
+>>> ujson.dumps([{"key": "value"}, 81, True])
+'[{"key":"value"},81,true]'
+>>> ujson.loads("""[{"key": "value"}, 81, true]""")
+[{'key': 'value'}, 81, True]
+```
+
+### Encoder options
+
+#### encode_html_chars
+
+Used to enable special encoding of "unsafe" HTML characters into safer Unicode
+sequences. Default is `False`:
+
+```pycon
+>>> ujson.dumps("<script>John&Doe", encode_html_chars=True)
+'"\\u003cscript\\u003eJohn\\u0026Doe"'
+```
+
+#### ensure_ascii
+
+Limits output to ASCII and escapes all extended characters above 127. Default is `True`.
+If your end format supports UTF-8, setting this option to false is highly recommended to
+save space:
+
+```pycon
+>>> ujson.dumps("åäö")
+'"\\u00e5\\u00e4\\u00f6"'
+>>> ujson.dumps("åäö", ensure_ascii=False)
+'"åäö"'
+```
+
+#### escape_forward_slashes
+
+Controls whether forward slashes (`/`) are escaped. Default is `True`:
+
+```pycon
+>>> ujson.dumps("http://esn.me")
+'"http:\\/\\/esn.me"'
+>>> ujson.dumps("http://esn.me", escape_forward_slashes=False)
+'"http://esn.me"'
+```
+
+#### indent
+
+Controls whether indentation ("pretty output") is enabled. Default is `0` (disabled):
+
+```pycon
+>>> ujson.dumps({"foo": "bar"})
+'{"foo":"bar"}'
+>>> print(ujson.dumps({"foo": "bar"}, indent=4))
+{
+    "foo":"bar"
+}
+```
+
+## Benchmarks
+
+*UltraJSON* calls/sec compared to other popular JSON parsers with performance gain
+specified below each.
+
+### Test machine
+
+Linux 5.0.0-1032-azure x86_64 #34-Ubuntu SMP Mon Feb 10 19:37:25 UTC 2020
+
+### Versions
+
+- CPython 3.8.2 (default, Feb 28 2020, 14:28:43) [GCC 7.4.0]
+- nujson    : 1.35.2
+- orjson    : 2.6.1
+- simplejson: 3.17.0
+- ujson     : 2.0.2
+
+|                                                                               | ujson      | nujson     | orjson     | simplejson | json       |
+|-------------------------------------------------------------------------------|-----------:|-----------:|-----------:|-----------:|-----------:|
+| Array with 256 doubles                                                        |            |            |            |            |            |
+| encode                                                                        |     22,082 |      4,282 |     76,975 |      5,328 |      5,436 |
+| decode                                                                        |     24,127 |     34,349 |     29,059 |     14,174 |     13,822 |
+| Array with 256 UTF-8 strings                                                  |            |            |            |            |            |
+| encode                                                                        |      3,557 |      2,528 |     24,300 |      3,061 |      2,068 |
+| decode                                                                        |      2,030 |      2,490 |        931 |        406 |        358 |
+| Array with 256 strings                                                        |            |            |            |            |            |
+| encode                                                                        |     39,041 |     31,769 |     76,403 |     16,615 |     16,910 |
+| decode                                                                        |     25,185 |     24,287 |     34,437 |     32,388 |     27,999 |
+| Medium complex object                                                         |            |            |            |            |            |
+| encode                                                                        |     10,382 |     11,427 |     32,995 |      3,959 |      5,275 |
+| decode                                                                        |      9,785 |      9,796 |     11,515 |      5,898 |      7,200 |
+| Array with 256 True values                                                    |            |            |            |            |            |
+| encode                                                                        |    114,341 |    101,039 |    344,256 |     62,382 |     72,872 |
+| decode                                                                        |    149,367 |    151,615 |    181,123 |    114,597 |    130,392 |
+| Array with 256 dict{string, int} pairs                                        |            |            |            |            |            |
+| encode                                                                        |     13,715 |     14,420 |     51,942 |      3,271 |      6,584 |
+| decode                                                                        |     12,670 |     11,788 |     12,176 |      6,743 |      8,278 |
+| Dict with 256 arrays with 256 dict{string, int} pairs                         |            |            |            |            |            |
+| encode                                                                        |         50 |         54 |        216 |         10 |         23 |
+| decode                                                                        |         32 |         32 |         30 |         20 |         23 |
+| Dict with 256 arrays with 256 dict{string, int} pairs, outputting sorted keys |            |            |            |            |            |
+| encode                                                                        |         46 |         41 |            |          8 |         24 |
+| Complex object                                                                |            |            |            |            |            |
+| encode                                                                        |        533 |        582 |            |        408 |        431 |
+| decode                                                                        |        466 |        454 |            |        154 |        164 |
diff --git a/README.rst b/README.rst
diff --git a/setup.cfg b/setup.cfg
@@ -1,8 +1,8 @@
 [metadata]
 name = ujson
 description = Ultra fast JSON encoder and decoder for Python
-long_description = file: README.rst
-long_description_content_type = text/x-rst
+long_description = file: README.md
+long_description_content_type = text/markdown
 url = https://github.com/ultrajson/ultrajson
 author = Jonas Tarnstrom
 license_file = LICENSE.txt