Basic API documentation

Add a stub page to generate autodoc-based API documentation for use
with Sphinx.

Include the mudpy logo

A basic SVG rendering of the original mudpy logo, for use in
documentation builds.

Add client configuration notes

This covers the last of the content from the old mudpy Web site, a
stub page with an example configuration for 8-bit Telnet clients.

Document the data model

Add some prose documenting the terminology for the mudpy data model.
Include brief descriptions of element groups within the .mudpy
top-level namespace, as well as _prefixed local variables in the
individual storage units (currently YAML format files).

Add configuration guide

Document the current configuration options along with their data
types and examples use.

Update coder guide for new site redirects

A number of stable HTTP redirects have been added as part of a mudpy
Web site overhaul, so switch to using those in documentation in an
effort to require fewer URL updates in the future.

Standardize formatting for the coder guide

In preparation for combining existing documentation into a cohesive
manual, adjust formatting of the coder guide for consistency with
other documents.

Switch to extensionless README and LICENSE files

Since the README and LICENSE files are going to get included into
reStructuredText files for documentation rendering, they don't
really need .rst extensions and this keeps them more consistent with
the AUTHORS and ChangeLog files generated by PBR.

Reformat README.rst

In further preparation for embedding the README.rst in Sphinx
rendered documentation, shorten the title, switch the copyright
statement from a field to a comment and while here clarify that the
YAML version used for configuration data is explicitly YAML 1.1.

Test that unknown telnet commands are filtered

Using the recently added support for injecting raw bytes into the
client socket in self tests, send a made-up IAC sequence which the
server won't recognize as a valid telnet command and make sure that
it gets properly logged and filtered out of the input sequence while
preserving the remaining input.

Fix TypeError with IAC escaping

Declare the literal newline as a byte type when analyzing an input
sequence with a double IAC byte, fixing a lingering crash which
raised a TypeError in negotiate_telnet_options(). Add regression
testing for proper handling and deduplication of an inline IAC pair.
While we're here, improve the log message about undecodeable UTF-8
sequences to be clear it's not just some of the bytes which were
discarded.

Trim readme file

In preparation for embedding the README.rst in rendered
documentation, remove the final paragraph referring to the included
docs and URL to the version published online.

Update login and banner art

Replace the old login splash screen and menu banner ASCII art with
something a little more stylish.

Test sample data style with yamllint

Add a tox environment and associated support for running the
yamllint YAML style checking utility. This tool should be used to
check all edits made to any included YAML files for ease of
readability and future maintenance. It can also be used to check
YAML data generated by the mudpy engine, as its output style matches
the expectations of yamllint's default ruleset. One override has
been added via the included .yamllint configuration file, to prevent
it complaining about the extremely long PBKDF2 password hashes in
account elements which can't effectively be line-wrapped when
written.

Indent block sequences in emitted files

Override the default Emitter and Dumper from the pyyaml library to
introduce (or more specifically stop suppressing) indentation when
writing block sequences. Also adjust the dump parameters to match
the indentation and related style used for included sample data and
configuration files.

Convert mappings and sequences from flow to block

For ease of readability, standardize on indented block-style YAML
mapping and sequence definitions in sample data and configuration.
Also wrap long lines, add explicit document start markers and
introduce spaces in commented lines to ease future checking with the
yamllint utility's default style rules.

Disconnect user on ConnectionResetError

If sending to a user's socket results in a connection reset
response, treat this as the same as a broken pipe and clean up the
session.

Be careful about marking facets modified

Make sure to only set the modified flag on a facet when setting a
value if it has no corresponding node in its origin or the value
differs. This prevents the engine from unnecessarily rewriting the
origin's backing file on startup or reload.

Use "group" instead of "category"

Update all uses of category/categories to group/groups. Also add
selftests for the "show groups" and "show group <group>" commands.

Drop old-style Element support

The transition to the new data model is complete, and support for
the old model is now removed.

Convert sample data to new style

Use the new data model for the sample room and prop definitions.

Use new style for menu definitions

Convert menus to the new data model.

Convert command Elements to new-style

Apply the new data model to command definitions.

Switch archetypes to new-style Elements

Apply the new data model to archetypes.

Switch internal counters to new-style Element

Convert the internal:counters Element to internal.counters following
the new data model.

Switch actors to new-style elements

Actor elements created for avatars now follow the new data model.

Handle connection reset in selftest

Within the selftest framework, catch ConnectionResetError exceptions
and provide a clearer error.

Make new-style facet deletion more robust

When destroying a new-style Element, reuse the delete_facet method
instead of deleting keys from the origin. Within the delete_facet
method, make sure to delete the corresponding key from the facethash
too.

Catch Exception when necessary

In situations where any exception needs to be matched in an except
clause, specify the Exception base class so as to be explicit that
it's an intentional choice and not an accidental omission.

Clearer selftest errors on disconnection

Catch EOFError in the selftest framework and emit a message
indicating what happened.

Use new-style elements for accounts

Switch account elements to the new data model, and fix some
old-style assumptions in Element creation and destruction. Also use
(and coerce to) boolean values for the administrator facet, and be
more clear in logs when accounts authenticating are admins or not.

Fix unhandled exception in show file command

When generating the list of nodes from a file for the "show file"
command output, treat the data attribute as a list rather than a
dict. Previously, use of this command would crash the interpreter on
an unhandled exception attempting to invoke a nonexistent (since the
data model conversion) .keys() method.

While we're here, correct the output preamble to refer to the file
contents as "nodes" instead of "elements since it also includes
non-element nodes. Also correct the error message when a nonexistent
file is requested to say "file" instead of "category" (this was
probably cut-n-pasted from "show categories" and missed getting
updated).

For future safety, add a selftest to exercise the "show files"
command.

Display flags in show files output

When the "show files" command is issued, any optional file flags
such as "private" are displayed after the filename.

Also add a selftest to exercise this command.

Clean up a stray comment in find_file

Remove a long-lived cruft comment line from the data.find_file()
function, obsoleted back when filename normalization was broken out
of the return line into some more explicit earlier calls (prior to
the initial archive import into Git).

Add descriptions to sample datafiles

For improved clarity, add some basic descriptions to the provided
sample datafiles in "_desc" metadata keys.

Move sample datafile copyrights into metadata

Instead of using YAML comments in the provided sample datafiles,
standardize on a "_copy" metadata key for greater extensibility.

Data nodes starting with "_" are metadata

Avoid loading data nodes with a "_" prefix as Universe content.
These are only used as file-local metadata.

Interpret a "." prefix as the startdir

Since daemonization explicitly changes the working directory to "/",
specifying a mudpy.filing.prefix of "." should be taken to refer to
the original starting directory recorded in Universe.startdir rather
than the current directory for the process.

Overhaul data management to get rid of __control__

Remap __control__ subkeys in data as follows:

    default_files -> .mudpy.filing.categories
    include_dirs -> _load
    include_files -> _load
    read_only -> _lock

Additionally, obsolete the __control__.private_files key by
switching from raw file/directory names to associative arrays in the
category defaults so that flags such as "private" can be added to
them, and make the category filenames automatically determined so
that they can be omitted unless specific overrides are required.

For the sake of future-proofing, rename the DataFile class to Data
and its "filename" attribute to "source" so that we avoid confusing
renames later when these might instead refer to some other storage
medium such as a table in a database. Similarly rename the Element
class attribute "filename" to "origin" attribute both to make it
more generic and to avoid confusion with "source" (an Element's
origin is a complete Data object, while a Data's source is just a
rooted-anchored file path currently).

Add a Universe.add_category convenience method to handle properly
guessing the corresponding fallback path and copying any declared
flags.

Error if set command is used on read-only element

It is possible for an admin to accidentally attempt to set a facet
on an element from a read-only file. If this happens, trap the
PermissionError exception and return a clear error message to the
user instead of crashing the service. Also add a regression test to
make sure this continues to work as intended, since preventing
alteration of read-only elements is a critical security measure we
need to make certain we preserve going forward.

Refuse to alter read-only elements at runtime

In the Element.set() method, check whether the element being altered
is from a read-only file. That should only ever happen when
(re)loading of files is underway, either at start time or because
the reload command/SIGHUP has been issued. If an attempt is made to
change a read-only element at any other time, raise a
PermissionError exception instead of setting the new value in memory
(altered values were never written to the backing file, but prior to
this it was possible to modify the in-memory copies).

Track whether loading is underway

In preparation for safeguards preventing alteration of elements from
read-only backing files, we need a way to identify that loading
updated files is in progress; that's the only time elements from
read-only files should ever change.

Test the set command

Add a test to make sure the set command works, and use it to alter
the facet we're subsequently checking in the writeable element for
the show element test to make sure it actually worked.

Use writeable element in show element test

In preparation for being able to test the set command, switch the
legacy element being shown to one which is not in a read-only file
so that we'll be able to test altering it in a future change.

Update copyright dates for files changed this year

Bump the copyright date to the present for files which received
significant modification since the beginning of the year.

Rename internal:storage to .mudpy.filing

Convert the old style internal:storage element to a new style
.mudpy.filing element and adjust the find_file() function
accordingly.

Stop unnecessarily stripping quote marks

Since the switch to YAML, quotations around strings are
automatically interpreted an so not included in the parsed result.
Remove legacy code which stripped leading and trailing quotes from
string values as this is no longer needed.

Explicitly configure the root_path in examples

In the example and test configurations, set the root_path value to
"." signifying the current/starting directory. This exercises the
option so we can make sure it doesn't break anything.

Log missing file inclusions as more severe

When another file is included with an inc macro in text, being
unable to load that file could indicate a fairly serious
configuration error. Increase the severity of the log message for
this so that it will be more easily noticed and caught in testing.

Fix file pathing in daemon mode

If run as a daemon, the working directory is reset to "/" for
safety. Make sure that relative file searching takes this into
account and prefixes with the original (pre-chdir) start directory
rather than the current working directory.

Rename internal:time to .mudpy.timing

Convert the old style internal:time element to a new style
.mudpy.timing element and adjust the User.check_idle() method and
on_pulse() function accordingly.

Switch example listening port from 6669 to 4000

As a nod to the legacy of DikuMUD, use 4000/tcp as the example
listening socket instead of 6669/tcp.

Fix facets method to give new-style relative names

For new-style elements correct the facets method to return short
(relative) key names, maintaining parity with old-style elements.
Add a new-style element to the "show element" selftest so that we
can make sure it won't regress.

Use importlib in place of imp

As of Python 3.4, the newer importlib module supports the reload()
function we need. Switch from the deprecated imp module, except
before 3.4 where we will simply pretend imp is importlib for
readability.

Reduce the log message priority for reload calls

It's important to log when the "reload" command is issued, but it's
not an error condition. Log the event at priority 6 rather than 8.

Exercise the reload command in tests

To make sure it doesn't get broken in a coming change, call the
admin command `reload` in the selftest.

Switch quoting styles to reduce escaped quotes

In an effort to address leaning toothpick syndrome, adjust quoting
styles where possible to avoid escaping quote marks without
increasing ambiguity.

Use raw strings when escape sequences are needed

Python 3.6 has added a DeprecationWarning for any regular strings
containing non-doubled backslash escapes. Use raw strings for these
instead so we'll be ready when the old syntax is eventually
disallowed.

Correct name of the custom loglevel test

Make the name of the custom loglevel test distinct from the show log
test preceeding it.

Handle ValueError when setting incorrect type

Trap for ValueError exceptions when attempting to pass a value to
the set command with an incorrect data type for the facet being set,
returning a clear failure message to the calling user.

Coerce loglevel facet to int when updating

Calling the set command always results in updating values to type
str, which can result in failures when those values are later
re-read. Explicitly coerce the loglevel value to int whenever it is
updated to avoid a subsequent exception when calling the show log
command.

This points out a need for maintaining a schema so that values can
be coerced to the appropriate type when needed, but for now the
conditional adjustment can serve as a placeholder for a more
thorough design.

Clear vestigial ord() calls in telopt negotiation

Clean up missed ordinal recasting on telnet options during
negotiation. They're no longer necessary, and crash the service if
triggered.

Stop using vary_rounds with passlib

The passlib library has deprecated the vary_rounds KDF parameter
since it's basically pointless as long as a strong salt is employed.
Proactively remove the reference as it will no longer be accepted by
passlib 2.0.

Guard against KeyError on universe.contents index

When accessing base level configuration elements from the main
engine, check that they're actually in universe.contents before
trying to retrieve their facets. Also use sane default fallbacks if
they're undefined.

Enable initial admin account in example config

The example etc/mudpy.yaml, intended for demonstration purposes,
only binds a listening socket on the loopback interface so shouldn't
be exposed remotely. As a result, turn on the configuration option
to enable elevating the account named "admin" to administrative
privileges automatically upon creation. This allows to run tests of
admin-specific commands with the example configuration.

Also rename the "testadmin" account used by the selftest to match
the name of the default for consistency, and rename test_config.yaml
to test_daemon.yaml reflecting its primary purpose (and also to open
the way for additional test configs as well).

Ignore unpacked *.egg directories

When performing in-tree sdist installs, stray *.egg directories may
be left behind. Don't track them.

Modernize coder documentation

Update the coder docs to remove obsolete references to the old
git2gch script, include new information on testing expectations and
outline a recommended tox-based developer environment and workflow.

Add a generic tox env for sdist generation et al

Add a testenv:venv environment to the tox.ini as a convenience for
things like sdist/wheel building or generating documentation. Also
add the autogenerated files from running setup.py sdist and
bdist_wheel commands to the .gitignore file.

Add a suitable test config for the daemon

In service of more repeatable testing and improved feature coverage,
include a test fixture for a version of the normal sample
configuration with some additional non-default features enabled and
some settings tuned to values which make testing easier/faster (not
recommended for production use):

* allow "testuser" to automatically be an admin when created

* enable data backup copies but keep only 3 when rotating

* turn on file-backed logging

* background the daemon process once initialized

* write a pidfile

* inject status updates into logs every 25 ticks

* save and rotate datafiles every 5 ticks

Package the self-test script as an entrypoint

Move the self-test script into the Python package and define an
entrypoint for it in setup.cfg so a `mudpy_selftest` executable will
be installed.

Correct filesystem permissions on daemon module

When the executable script was moved to become an in-package module,
its permissions were incorrectly left executable. Correct them to
match the other modules in the package.

Make the self-test script importable

In preparation for moving the self-test script to a more standard
entrypoint, make it safely importable and give it a separate
conditional main() execution.

Add missing copyright/license notices

For clarity, add copyright and license notice headers at the tops of
files which were missing them (general packaging configuration and
metadata for the most part, but doesn't hurt to be thorough for the
sake of future provenance inquiries).

Support running flake8 under tox

Add the necessary configuration to be able to run `tox` for
performing style checks easily with flake8.

Package the daemon executable as an entrypoint

Move the daemon executable into the Python package and define an
entrypoint for it in setup.cfg so a similar `mudpy` executable will
still be installed. Drop the unnecessary import path override now
while at it.

Make the executable importable

In preparation for moving the executable to an more standard
entrypoint, make it safely importable and give it a separate
conditional main() execution.

Create a Python package

Add setup.cfg and setup.py files sufficient to create a "mudpy"
Python package suitable for `pip install` and uploading to PyPI.

Appease style checks

Once more the PEP8 gods stir to anger. Sate their fury with a
generous offering of whitespace, such that they might return to
their baleful slumber.

Clean up trailing whitespace in documentation

Remove some unsightly trailing whitespace in the readme and coder
reference.

Move documentation files for packaging preparation

Move doc/coder.txt into doc/source/ where Sphinx will expect it,
doc/LICENSE to the top-level directory renamed to LICENSE.rst for
clarity on its format, and similarly rename README to README.rst as
well.

Move lib/mudpy to mudpy for packaging preparation

Move the lib/mudpy tree to just mudpy where it will ultimately
reside once integrated into a Python package. Temporarily adjust the
module search path addition in the executable until packaging work
is complete (at which point it can safely be dropped).

Rename internal:process to .mudpy.process

Convert the old style internal:process element to a new style
.mudpy.process element and adjust the daemonize(), create_pidfile()
and remove_pidfile() functions accordingly.

Rename internal:network to .mudpy.network

Convert the old style internal:network element to a new style
.mudpy.network element and adjust the initialize_server_socket()
function accordingly.

Rename internal:directions to .mudpy.movement.*

Convert the old style internal:directions element to a series of new
style .mudpy.movement.* elements and adjust the move_direction()
function accordingly. Also extend the Universe class to provide a
set-based index of direction names found in the data.

Rename internal:logging: to .mudpy.log

Convert the old style internal:logging element to a new style
.mudpy.log element and adjust the log() function accordingly.

Update README for recent development

Edits to the README file reflect the switch to Py3K, YAML and
addition of non-stdlib dependencies.

Rename internal:limits element to .mudpy.limit

Convert the old style internal:limits element to a new style
.mudpy.limit element and rename the default_admins,
default_backup_count and max_avatars facets to admins, backups and
avatars respectively.

Strip extra separators in show element command

Eat leading and trailing "." separators in the show element command,
so that it will consistently search the element set for the
corresponding simplified element names.

Fix 8-bit Telnet with Py3K

Replace the lambda filter for non-ASCII characters with a list
comprehension, correcting and simplifying the range comparison and
recombination of the filtered string.

Rename internal:language: to .mudpy.linguistic

Convert the old style internal:language element to a new style
.mudpy.linguistic element and adjust the command_say() function
accordingly.

Implement new style element support

Add support for new style elements implemented as a flat associative
array of facets prefixed with their element names, and switching to
"." as a prefix separator. This is initially backward compatible
using a toggle and some sniffing of key names to distinguish old and
new style elements. Once the transition from old to new style has
been completed, the compatibility code can be cleaned up.

Test the show element command

Add a functional test for the show element command, to prevent
future regressions in it.

Simplify multiline matching in functional tests

To ease matching across more complex outputs in functional test
conversations, use compiled expressions with the DOTALL flag so that
the "." wildcard will also match newline characters in the stream.

Fix show element command for Py3K

Under Python 3, the dict.keys() method returns a generator rather
than a list and so cannot support the list.sort() method. Instead
use the sorted() function for this purpose in the show element
command. Also switch from concatenation to formatting to embed
facets in the output since they may contain nontext values.

Make escape_macros no-op on nontext values

Update the escape_macros() function to deal with YAML style
Element.get() that may return datatypes other than str. This allows
for indiscriminately passing facets through the function without
recasting them.

Check that functional tests log no errors

After all other functional tests, check the output of show log 7 to
make sure that no earlier tests caused errors at or above that
loglevel.

Test that the show log command works

Exercise the show log command in functional testing, and confirm
that it returns at least some log data.

Fix show log command for Py3K

The behavior of lambda filters has changed in Python 3 such that you
can no longer treat them directly as lists. Trivially reimplement
them as list comprehensions. Also correct a missing minimum loglevel
fallback default.

Fix recursive BrokenPipeException on disconnect

When an admin user has a broken pipe, attempting to log
BrokenPipeException errors to their socket raises another until the
max recursion depth is hit. Set the current user's state to
disconnecting before logging the error instead of after, so as to
avoid this loop.

Switch basic data loader unit from element to node

In preparation for a migration to a new flat data model where
elements are inferred from facet names, stop referring to the
top-level keys in data files as elements and instead call them
nodes. During the transitional period, a node could be an old-style
element or a new-style element's facet.