From 0719510decfc26e6b9ebd28d68c21c3685253bbc Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Fri, 23 Mar 2018 15:16:25 +0000 Subject: [PATCH] README: various improvements - format filenames as code - highlight data source types as bold, for readability - add links to dependencies - format sub-headings in "Description of files" section - improve line wrapping a bit - slightly reword a few passages for additional clarity --- README.md | 98 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 51 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index a0c6ab1..6db86a0 100644 --- a/README.md +++ b/README.md @@ -7,65 +7,69 @@ Online Encyclopedia of Integer Sequences (OEIS), as hosted on http://www.oeis.or Overview -------- -Our tools handle OEIS data from three sources: +These tools can handle OEIS data from three types of sources: -1. remote: the OEIS database residing on the oeis.org server. The remote database can be accessed via HTTP or HTTPS requests. -2. local sqlite3: a replica of the remote database as a local SQLite3 database file. -3. local pickle: the OEIS database a a local pickle-format file, used for local analysis. The "pickle" format is Python-specific. +1. **remote**: the OEIS database residing on the oeis.org server. + The remote database can be accessed via HTTP or HTTPS requests. +2. **local sqlite3**: a replica of the remote database as a local SQLite3 database file. +3. **local pickle**: the OEIS database a a local pickle-format file, used for local analysis. + The "pickle" format is Python-specific. -The local sqlite3 database is obtained from the remote database by an automatic web-crawler called 'fetch_oeis_database.py'. -It contains the sequence metadata in the internal format as it is used on the remote side, as well as so called 'b-file' -data that contain sequence data *a(n)* up to high values of *n*. +The local sqlite3 database is obtained from the remote database +by an automatic web-crawler called `fetch_oeis_database.py`. +It contains the sequence metadata in the internal format as it is used on the remote side, +as well as so called 'b-file' data that contain sequence data *a(n)* up to high values of *n*. -The local pickle format database is obtained from the local_sqlite3 database by parsing the data and turning it into OeisEntry -instances. The pickled list of all OeisEntry instances can be read in its entirety within a few seconds. +The local pickle format database is obtained from the `local_sqlite3` database by parsing the data +and turning it into `OeisEntry` instances. +The pickled list of all OeisEntry instances can be read in its entirety within a few seconds. -Apart from these sources that describe the OEIS data, we also use the "catalog", which is a Python module that contains -implementations of sequence generating functions. +Apart from these sources that describe the OEIS data, we also use the "catalog", +which is a Python module that contains implementations of sequence generating functions. Dependencies ------------ -- All code is written in Python 3. -- Some code depends on the 'numpy' library: - - show_database_time.py - - solve_linear_sequence.py -- Some code depends on the 'matplotlib' library: - - show_database_time.py +- All code is written in [Python 3](https://en.wikipedia.org/wiki/History_of_Python#Version_3). +- Some code depends on the [numpy](http://www.numpy.org/) library: + - `show_database_time.py` + - `solve_linear_sequence.py` +- Some code depends on the [matplotlib](https://matplotlib.org/) library: + - `show_database_time.py` Description of files -------------------- -Non-Python files: - -filename | description -----------------------------------|------------------------------------------------------------------------------------ -README.md | Text file (markdown format) description of the project. -catalog_files/*.json | Catalog files, describing parametrized sequence generating functions. - -Python scripts files: - -filename | description -----------------------------------|------------------------------------------------------------------------------------ -fetch_oeis_database.py | Fetch and refresh data from the remote OEIS database to a local sqlite3 database. -show_database_time.py | Visualize time stamps in a given local sqlite3 OEIS database. -parse_oeis_database.py | Parse a local sqlite3 database and produce a local pickle database. -find_sequences.py | Probe a local pickle database for a given sequence (work in progress). -pickle_to_json.py | Read a local pickle database and write a JSON version. -solve_linear_sequence.py | Find linear sequences in a local 'pickle' database. -check_database.py | Perform a number of checks on the data in a local pickle database. -verify_oeis_catalog.py | Verify the catalog. - -Python modules: - -filename | description -----------------------------------|------------------------------------------------------------------------------------ -fraction_based_linear_algebra.py | Perform matrix inversion without loss of precision using the Fraction type. -charmap.py | Defines lists of acceptable characters for the OEIS directives. -OeisEntry.py | Defines a simple class that contains (most of) the data of a single OEIS sequence. -timer.py | Simplifies timing lengthy operations using a context manager. -fetch_remote_oeis_entry.py | Fetches a single sequence's data from the OEIS website (www.oeis.org). -catalog.py | Access the local catalog. +### Non-Python files + +filename | description +------------------------------------|------------------------------------------------------------------------------------ +`README.md` | Text file (markdown format) description of the project. +`catalog_files/*.json` | Catalog files, describing parametrized sequence generating functions. + +### Python script files + +filename | description +------------------------------------|------------------------------------------------------------------------------------ +`fetch_oeis_database.py` | Fetch and refresh data from the remote OEIS database to a local sqlite3 database. +`show_database_time.py` | Visualize time stamps in a given local sqlite3 OEIS database. +`parse_oeis_database.py` | Parse a local sqlite3 database and produce a local pickle database. +`find_sequences.py` | Probe a local pickle database for a given sequence (work in progress). +`pickle_to_json.py` | Read a local pickle database and write a JSON version. +`solve_linear_sequence.py` | Find linear sequences in a local 'pickle' database. +`check_database.py` | Perform a number of checks on the data in a local pickle database. +`verify_oeis_catalog.py` | Verify the catalog. + +### Python modules + +filename | description +------------------------------------|------------------------------------------------------------------------------------ +`fraction_based_linear_algebra.py` | Perform matrix inversion without loss of precision using the Fraction type. +`charmap.py` | Defines lists of acceptable characters for the OEIS directives. +`OeisEntry.py` | Defines a simple class that contains (most of) the data of a single OEIS sequence. +`timer.py` | Simplifies timing lengthy operations using a context manager. +`fetch_remote_oeis_entry.py` | Fetches a single sequence's data from the OEIS website (www.oeis.org). +`catalog.py` | Access the local catalog. How it all fits together ------------------------