have to move README back to .md because of GitHub

1 files changed, 169 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b59b61c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,169 @@
+
+ASN.1 library for Python
+------------------------
+[![PyPI](https://img.shields.io/pypi/v/pyasn1.svg?maxAge=2592000)](https://pypi.python.org/pypi/pyasn1)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pyasn1.svg)](https://pypi.python.org/pypi/pyasn1/)
+[![Build status](https://travis-ci.org/etingof/pyasn1.svg?branch=master)](https://secure.travis-ci.org/etingof/pyasn1)
+[![Coverage Status](https://img.shields.io/codecov/c/github/etingof/pyasn1.svg)](https://codecov.io/github/etingof/pyasn1)
+[![GitHub license](https://img.shields.io/badge/license-BSD-blue.svg)](https://raw.githubusercontent.com/etingof/pyasn1/master/LICENSE.txt)
+
+This is a free and open source implementation of ASN.1 types and codecs
+as a Python package. It has been first written to support particular
+protocol (SNMP) but then generalized to be suitable for a wide range
+of protocols based on
+[ASN.1 specification](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.208-198811-W!!PDF-E&type=items).
+
+Features
+--------
+
+* Generic implementation of ASN.1 types (X.208)
+* Fully standard compliant BER/CER/DER codecs
+* 100% Python, works with Python 2.4 up to Python 3.6
+* MT-safe
+* Contributed ASN.1 compiler [Asn1ate](https://github.com/kimgr/asn1ate)
+
+Why using pyasn1
+----------------
+
+ASN.1 solves the data serialization problem. This solution was
+designed long ago by the wise Ancients. Back then, they did not
+have the luxury of wasting bits. That is why ASN.1 is designed
+to serialize data structures of unbounded complexity into
+something compact and efficient when it comes to processing
+the data.
+
+That probably explains why many network protocols and file formats
+still rely on the 30+ years old technology. Including a number of
+high-profile Internet protocols and file formats.
+
+Quite a number of books cover the topic of ASN.1. 
+[Communication between heterogeneous systems](http://www.oss.com/asn1/dubuisson.html)
+by Olivier Dubuisson is one of those high quality books freely 
+available on the Internet.
+
+The pyasn1 package is designed to help Python programmers tackling
+network protocols and file formats at the comfort of their Python
+prompt. The tool struggles to capture all aspects of a rather
+complicated ASN.1 system and to represent it on the Python terms.
+
+How to use pyasn1
+-----------------
+
+With pyasn1 you can build Python objects from ASN.1 data structures.
+For example, the following ASN.1 data structure:
+
+```bash
+Record ::= SEQUENCE {
+  id        INTEGER,
+  room  [0] INTEGER OPTIONAL,
+  house [1] INTEGER DEFAULT 0
+}
+```
+
+Could be expressed in pyasn1 like this:
+
+```python
+class Record(Sequence):
+    componentType = NamedTypes(
+        NamedType('id', Integer()),
+        OptionalNamedType(
+            'room',
+            Integer().subtype(
+                implicitTag=Tag(tagClassContext, tagFormatSimple, 0)
+            )
+        ),
+        DefaultedNamedType(
+            'house', 
+            Integer(0).subtype(
+                implicitTag=Tag(tagClassContext, tagFormatSimple, 1)
+            )
+        )
+    )
+```
+
+It is in the spirit of ASN.1 to take abstract data description 
+and turn it into a programming language specific form.
+Once you have your ASN.1 data structure expressed in Python, you
+can use it along the lines of similar Python type (e.g. ASN.1
+`SET` is similar to Python `dict`, `SET OF` to `list`):
+
+```python
+>>> record = Record()
+>>> record['id'] = 123
+>>> record['room'] = 321
+>>> print(record.prettyPrint())
+Record:
+ id=123
+ room=321
+>>>
+```
+
+Part of the power of ASN.1 comes from its serialization features. You
+can serialize your data structure and send it over the network.
+
+```python
+>>> substrate = encode(record)
+>>> hexdump(substrate)
+00000: 30 07 02 01 7B 80 02 01 41
+```
+
+Conversely, you can turn serialized ASN.1 content, as received from
+network or read from a file, into a Python object which you can
+introspect, modify, encode and send back.
+
+```python
+>>> received_record, rest_of_substrate = decode(substrate, asn1Spec=Record())
+>>>
+>>> print(received_record.prettyPrint())
+Record:
+ id=123
+ room=321
+ house=0
+>>>
+>>> record == received_record
+True
+>>> received_record['room'] = 123
+>>> substrate = encode(received_record)
+>>> hexdump(substrate)
+00000: 30 06 02 01 7B 80 01 7B
+```
+
+With ASN.1 design, serialization codecs are decoupled from data objects,
+so you could turn every single ASN.1 object into many different 
+serialized forms. As of this moment, pyasn1 supports BER, DER and CER
+formats. The extremely compact PER encoding is expected to be introduced
+in the upcoming pyasn1 release.
+
+More information on pyasn1 APIs can be found in the
+[documentation](http://pyasn1.sourceforge.net),
+compiled ASN.1 modules for different protocols and file formats
+could be found in the pyasn1-modules 
+[repo](https://github.com/etingof/pyasn1-modules).
+
+Download
+--------
+
+The pyasn1 package is distributed under terms and conditions of 2-clause
+BSD [license](http://pyasn1.sourceforge.net/license.html). Source code is freely
+available as a Github [repo](https://github.com/etingof/pyasn1).
+
+Installation
+------------
+
+Download pyasn1 from [PyPI](https://pypi.python.org/pypi/pyasn1) or just run:
+
+```bash
+$ pip install pyasn1
+```
+
+Getting help
+------------
+
+If something does not work as expected, 
+[open an issue](https://github.com/etingof/pyasn1/issues) at Github or 
+post your question [to Stack Overflow](http://stackoverflow.com/questions/ask)
+or try browsing pyasn1 
+[mailing list archives](https://sourceforge.net/p/pyasn1/mailman/pyasn1-users/).
+
+Copyright (c) 2005-2017, [Ilya Etingof](http://etingof@gmail.com).
+All rights reserved.