Add the beginnings of an admin guide

Some initial prose to seed the admin guide, taken from various
E-mails to users in recent months.

Collapse redundant exceptions

In User.enqueue_input() combine a redundant match on BlockingIOError
and OSError since the former is a subclass of the latter. This was
caught by the B014 check introduced in flake8-bugbear 20.1.1.

Indicate support for Python 3.9

Python 3.9 is well into its second alpha, is a recognized trove
classifier on PyPI, and all mudpy changes are being successfully
tested against it. Add the classifier to our package metadata to
reflect this.

Link the ChangeLog from package metadata

Users of PyPI are going to want to know where to find the ChangeLog
without going to the project homepage/docs and hunting around. Add a
flexible redirect URL for it so we can move it easily later.

Drop section numbering from documentation builds

Sphinx section numbering leads to confusing output, particularly for
the rendered ChangeLog. Remove it.

Update copyright year in the LICENSE as this is the first change of
the new year, and similarly update it in rendered documentation
footers as this is the first documentation change of the year.

Make sure all command functions return True

Because recent adjustments to handler_active() rely on the
call_handler_function() return value to determine whether something
went wrong, we need command functions to return something which
evaluates boolean True if they ran to completion and didn't raise an
exception. Just return True from all of them for now, but they may
see more dynamic result handling in the future.

Increase timer resolution in test config

Significantly speed up the timer in the test config (by a factor of
1000). On fast machines with cached tox envs, this results in an
order of magnitude improvement in test runtime. Related timer values
are lengthened to avoid test failures due to timeouts, and some
others are shortened for consistency.

This is obviously not suitable for normal operation, so the sample
configuration remains untouched and thus the tox selftest_config
testenv does not benefit from it.

Use call_hook_function() in handler_active()

Simplify mudpy.misc.handler_active() by making it a wrapper around
the more general mudpy.misc.call_hook_function() which was
originally derived from it.

Preserve loglines on reload

When a reload occurs, prepend the new universe's loglines with those
from the old universe so they are not lost. This may temporarily
bloat the loglines list slightly over the limit, but it will be
adjusted downward the next time anything new gets logged. Also
adjust the `show log` selftests to handle linewraps in a new place
when the total loglines count is higher.

Set bandit to error on risks of any severity

Now that the last of the low-level risks has been reviewed and
whitelisted, remove the severity filter from the bandit command so
that incorporation of any unexpected risks it can spot will be
blocked for future commits.

Whitelist uses of stdlib random module for bandit

There are currently two uses of random.randrange() and one of
random.choice() for non-security/non-crypto purposes. Mark them as
whitelisted for bandit checks and add comments explaining why.

Clean up function names in menu definitions

Now that the functions called from menus are filtered and resolved
safely rather than being directly executed, the explicit mudpy
package name and the user parameter passing are no longer necessary.
Remove them from the function names in menu definitions and also
drop the old compatibility code which trims them.

Ratchet bandit checking down to medium severity

Now that the last of the medium-severity risks have been eliminated,
adjust the bandit command line so that it will prevent addition of
any new instances.

Replace eval() and exec() use for menu functions

Add a new misc.call_hook_function() routine based on the existing
command execution in misc.handler_active() to eliminate all use of
eval() and exec() built-ins in menu operations.

Relocate main_utility menu functions

Move the action and demand logic for the main_utility state from
their respective facets to the menu module, hiding them behind
consistently-named entry points.

Relocate delete_avatar menu functions

Move the action and create logic for the delete_avatar state from
their respective facets to the menu module, hiding them behind
consistently-named entry points.

Relocate delete_account menu function

Move the action logic for the delete_account state from its
corresponding facet to the menu module, hiding it behind a
consistently-named entry point.

Relocate choose_name menu functions

Move the action and create logic for the choose_name state from
their respective facets to the menu module, hiding them behind
consistently-named entry points.

Relocate choose_gender menu function

Move the action logic for the choose_gender state from its
corresponding facet to the menu module, hiding it behind a
consistently-named entry point.

Relocate checking_new_account_name menu functions

Move the action logic for the checking_new_account_name state from
its respective facets to the menu module, hiding them behind
consistently-named entry points.

Relocate activate_avatar menu functions

Move the action and create logic for the activate_avatar state from
their respective facets to the menu module, hiding them behind
consistently-named entry points.

Add a mudpy.menu module to hold menu functions

In preparation for relocating arbitrary Python expressions out of
the standard menu elements, provide a stub mudpy.menu module which
will house equivalent convenience functions and include an autodoc
section for it in the Sphinx API documentation template.

Move selected menu item into the User object

In order to simplify menu handlers, move the active choice into an
attribute of the User class so that only one object needs to be
handed off, and update menus accordingly.

Rename state variable in get_menu_choices()

Avoid shadowing the new menu module in misc.get_menu_choices() by
renaming its menu variable to state, which is also more consistent
with other menu-related functions.

Remove exec() from handle_user_input() function

Stop passing the constructed handler function name into an exec()
and instead reference it from the globals() dict.

Eliminate exec() in Universe.new()

Replace questionable exec call in the new() method of the Universe
class with cleaner getattr/setattr equivalents.

More thoroughly test account and avatar menus

Split up the teardown "test" into separate tests for avatar and
account deletion. Avatar deletion was previously not being exercised
correctly, instead avatar deletion aborting was what was actually
being tested. Add separate tests that the avatar and account
deletion default actions are to abort. Also add a test of the avatar
creation limit.

Properly escape punctuation in test patterns

Make sure all literal question marks (?) and periods (.) in selftest
match patterns are backslash-escaped in raw strings.

Tighten up eval() scope in show result subcommand

In order to slightly reduce risk but mostly to increase convenience
with the `show result` administrative subcommand, replace its eval()
invocation's globals with just the mudpy module namespace and the
actor's universe pointer as "universe" (this way exploratory
expressions don't need to do things relative to actor.universe all
the time). Extend the selftest to confirm these are present and that
any attempts to access other globals and locals within the
command.show() function's scope raise an exception.

Whitelist this intentional use of eval() for bandit analysis.

Replace uses of exec() in module loader

Improve the module loader to avoid the more dangerous exec()
function in favor of smarter use of importlib. This allows us to
drop some flake8 whitelisting. Also switch out the hard-coded module
list (which missed addition of the daemon module) with a more
dynamic routine on Python 3.7 and later, which will use all *.py
files in the top level of the package so none are forgotten in the
future. Keep a hard-coded fallback list for support of earlier
Python versions, but compare the two so this list is guaranteed
complete for as long as it is maintained.

Use generic authors for copyright shown in docs

Adjust the copyright holder listed in the Sphinx-built documentation
to match the more general "mudpy authors" used in copyright headers
for files.

Update copyright for files edited in 2019

These files missed a copyright year bump when they were edited.

Satisfy yamllint checking of .yamllint

The 1.18.0 release of yamllint has started linting its .yamllint
config file by default. Add a document marker at the top of the file
so that it will pass document-start rule.

Log User object ID even when account is an admin

Adjust authentication logging to consistently record the User object
instance ID regardless of, and separately from, whether the account
which authenticated is an administrator.

Log starting directory during initialization

Update the initialization logging to also include the starting
directory, since some of the startup routines form their file paths
relative to it.

Separate listening port in startup logging

Using a port separator of ":" is vague in combination with IPv6
addresses, so separate the listening port number more clearly in the
startup log message.

Disable usedevelop for some tox testenvs

Tox's usedevelop option implicitly installs the project and its
dependencies, and is enabled in the base testenv. Disable it in
testenvs which don't make use of the installed project, but add the
project dependencies to the docs testenv since it needs them to be
able to generate the API docs. This results in a fairly substantial
speedup of >10% for a full `tox` invocation.

Correct reference to main config in walk-through

The main sample configuration is mudpy.yaml, not mudpy.conf.

Add info on what's missing and included

To properly set expectations, update the README file with
information on the current state of development, what's done so far
and what's not yet.

Add a demo walk-through to the coder guide

Include an example of a simple development environment setup,
explaining how to start the server using the provided sample
configuration and then interact with it using a console-based MUD
client.

Recommend the tox-venv plug-in

In the coder guide, include a suggestion for tox-venv (a tox plug-in
which makes tox use the venv module from the Python 3 standard
library in place of the separate virtualenv package).

Link API documentation in the coder guide

In the API section of the coder guide, add a cross-link to the API
documentation for the package and modules.

Drop Python 3.4 and add 3.8

Python 3.4 reached end-of-life status nearly 4 months ago with the
release of 3.4.10 on 2019-03-18, so stop asserting we test new
commits against it (truth be told, it was already hard to build on
modern distros with newer libssl anyway).

Python 3.8 has been in beta for over a month already, and 3.8.0b2
was tagged earlier this week. New commits have been tested against
3.8 alpha and beta builds for a while, so add it to the list of
trove classifiers.

Update the README file to stop mentioning minimum Python 3 versions,
so that it won't need further updates as older interpreters age out.

Update minimum PBR for setup_requires

Some of the recently-added Python package metadata (particularly
project_urls and description-content-type) need newer PBR where that
support was added. PBR 5.0.0 is the oldest version with the
particular features we're using, so update the lower bound for it
accordingly.

Improve preferences display

When displaying preferences, color-code the base and admin
preferences similar to command help. Also show a placeholder when
there is no existing value set for a preference. Add a hyphen
separator between preference names and values. Update tests to
accommodate the new formatting, and while we're there add a test to
make sure non-admins can't set values for admin-only preferences.

Support abbreviating portal names when moving

Allow users to abbreviate portal names provided to the move command
for convenience.

Provide normal error if command raises exception

If a attempting to execute a user-supplied command results in a
Python exception, return the normal error message string to the user
(in addition to logging the exception and traceback). This way,
normal users won't see any difference between unknown/invalid
commands and broken ones.

Safely log when a command error cannot be sent

If a command triggers an error back to the user and sending that
error raises an exception, log it and continue to avoid crashing the
engine.

Correct data type for see_also command facets

Make the see_also facets of the chat and say commands list items as
they were originally intended to be, and test that they get
displayed.

Show possible abbreviations in help list

When listing available commands via the help command, show which
parts of a given command word are optional to type. Also test it.

Correct logged error for missing action function

When logging an error for a missing command action function,
correctly include the function name. Also go ahead and add the
action name sought for improved clarity.

Make command actions implicit

If an action is not listed for a command, assume the action function
is named the same as the command itself.

Dereference command action functions

Replace the use of Python expressions for command actions with
simple names of functions relative to the mudpy package namespace.
This removes an unsafe use of exec(). Also start catching all
exceptions raised by the execution of a command and simply logging
them rather than allowing them to crash the engine.

Test the show result command

Add self test coverage for the show result administrative command,
both with a working expression and one which raises an exception.

Correct a TypeError in the show time command

Add missing type conversion in the output of the show time
administrative command, and include a regression test so we assure
it continues to work.

Always pass parameters in commands

When calling a command handler, pass a parameters object regardless
of whether the command actually needs one. This normalizes the
interface between command actions and their corresponding handler
functions so they can be called through a generic interface in the
future.

Don't allow abbreviating administrative commands

If a command is flagged as administrative, don't match substring
abbreviations for it. For example, an admin entering "h" should get
the help summary, not halt the engine.

Show full command name in help output

When help is requested on an abbreviated command, include the full
name (rather than the provided abbreviation) in the synopsis.

Implicitly support abbreviating commands

Match entered commands against initial substrings of a sorted list
of command keywords, effectively supporting abbreviated commands.
Also test it works.

Allow including time in the active state prompt

Occurrences of $(time) in the user's prompt string will be replaced
by the current World clock increment when displayed. Also test this
works as intended.

Escape replacement macros in preferences

Don't let users inject replacement macros into their preferences,
just escape them so they're harmless. Also adjust the preferences
tests to include macros so this safety measure does not regress.

Test that macros are escaped in communication

We explicitly escape replacement macros in user input for
communication commands (say, ask, et cetera). Test to make sure this
safety measure does not regress.

Use the active state prompt as the default prompt

In order to stop hard-coding the default prompt string into the
prompt method, use the prompt string associated with the active
state to provide it. This is intuitive and allows it to be more
easily overridden if desired.

Add a prompt generator method

Move the retrieval and assembly of the prompt string fragment for
active state users into its own method, paving the way for more
dynamic and extensible prompts.

Fix selftest telopt callback for Python 3.4

Python 3.4 is unable to handle formatted bytestrings. Replace two
occurrences in the Telnet option callback handler in the selftest
script to use concatenation operators instead.

Use ISO 8601 time in logs

For ease of readability, switch log timestamps from traditional
"asctime" format to ISO 8601 date and time.

Test for high-severity vulnerabilities with bandit

Use the bandit analyzer to check non-test-related Python source code
for potential vulnerabilities. To start, only error on matches with
severity "high" (we can ratchet it down later as lower-severity
items are addressed).

Test with the bugbear plugin for flake8

Add the bugbear plugin to the flake8 tox testenv, and mark as
private a couple of loop control variables it identified (B007).

Fix comparisons for pyflakes 2.1

The latest release of flake8 updates to pyflakes 2.1, and with that
comes an expectation that typical variable equality comparisons
should avoid the use of "is" and "is not" for safety. Adjust a
couple places we previously ran afoul of the new F632 check.

Safely log unknown Telnet options and commands

During Telnet negotiation, log unknown options by numeric value if
there is no listed name for them. Do the same for unknown Telnet
commands, though in reality this should never happen as they get
filtered by the existing implementation. Add regression testing to
make certain the crash bug which this fixes doesn't recur.

Be explicit about test requirements in tox.ini

Only a couple of the testenvs listed in tox.ini actually made use of
the packages claimed as general test dependencies inherited by all
testenvs. Move these to their corresponding declarations and drop
the old test-requirements.txt file.

Switch to passlib.PasswordHash.hash

Starting with passlib 1.7 the PasswordHash.encrypt() method has been
renamed to PasswordHash.hash() for clarity, and the old name
deprecated. Use the new name and update our minimum passlib
dependency version accordingly.

Add support for user preferences

Make it possible for users to list, view and set values of any
account facets white-listed in configuration. Also add
administrator-only preferences as a convenience option. To have a
means of exercising this, make the active state prompt dynamic so
that each user can set it as a preferences. Include sample
configuration, regression tests and documentation.

Add 2019 to copyright for docs and license

A new year is upon us, and changes committed in 2019 warrant
increasing the copyright range for documentation and the full
license text to indicate that.

Rename command.set to command.c_set

In order to avoid shadowing any built-in set() method for Python
modules, rename the set() function defined in the command module to
c_set() and adjust the corresponding caller for the "set"
administrative command accordingly.

Support using tox-venv for testing

The tox-venv plugin for tox leverages the venv module from the
Python 3 standard library instead of relying on the third-party
virtualenv project. Its environments differ in minor ways, however,
so to accommodate that we adjust a couple of our tox testenvs. The
dist testenv no longer assumes the wheel package will be installed,
and expressly includes it as a dep. The docs testenv preinstalls
mudpy into the environment so that we can be sure PBR generates the
AUTHORS and ChangeLog files before Sphinx attempts to include them
in any rendered documents.

Rename debug testenv to demo and use sample config

Switch the tox testenv name for invoking the daemon to demo, and
also switch it to implicitly using the default sample configuration
in etc/mudpy.yaml rather than explicitly using the daemon config
from the test fixtures. This makes it a little more friendly for
developers and/or first-time users who want to try things out since
`tox -e demo` will get them the log streaming to stdout and the
process bound to the invoking terminal where they can terminate it
with a simple sigint. For those who want to use a different
configuration, it can be passed with a command-line argument, like
`tox -e demo mudpy/tests/fixtures/test_daemon.yaml` (as an example
to replicate the old "debug" behavior).

Use yamllint --strict when called from tox

To treat YAML formatting inconsistency warnings from yamllint as
blocking errors for development, invoke it with --strict so that tox
will report a failure rather than success.

Move commands into a separate command module

For ease of maintainability, move all the mudpy.misc.command_*()
functions into their own module accessible via mudpy.command.*()
instead. In order to accomplish this, User objects now carry a
universe attribute so that commands they call can identify the
correct universe object in which to act.

Alphabetize the command functions, update the corresponding function
calls in the command elements, add the new module to the API
documentation, and include it in the dynamic module reload list.

Update admin command help for new data model

Refresh the example invocations in help entries for admin commands
which previously showed old-style element identifiers.

Alphabetize the `help show` subcommand entries

When categories were renamed to groups, help details for the
corresponding show subcommands were updated in-place rather than
getting reordered to maintain the existing alphabetization. Fix it.

Don't LBYL when creating missing data directories

It's better to ask forgiveness than permission. Just try to create
parent directories for any data file, and don't error if they
already exist.

Try to make missing pidfile and logfile parent dir

Rather than assume the path to a specified pidfile or logfile
already exists, try to make it before opening the file for writing.
This solves an issue with `tox -e debug` raising FileNotFoundError
when trying to open the logfile. Remove the mkdir() call in the
selftest setup so that this gets exercised properly.

Update copyright dates for files changed in 2018

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

Add navigation links to Sphinx config

Similar to the project URLs in the Python package configuration,
include some useful hyperlinks in the Sphinx Alabaster sidebar for
things like code browsing/cloning, bug reporting and release files.

Reorganize Sphinx config

For improved manageability, sort the contents of the Sphinx conf.py
file alphabetically, and switch to the same indentation style as the
rest of the codebase.

Clarify Python version support in README

Make it more apparent that testing is being performed as far back as
Python 3.4, which doesn't exclude the possibility that it may also
be made to work with Python 3.3 on platforms where that can still be
compiled/installed.

Generalize copyright headers in files

Since we're distributing an AUTHORS file even in wheel packages now
replace the specific copyright strings with ones which generally
mention "mudpy authors" instead, refer to the AUTHORS file and Git
history from the LICENSE file, and embed the generated list of
authors in rendered versions of the license.

Add AUTHORS file to wheel

Now that Wheel 0.32 supports a list of license_files we can
incorporate the AUTHORS file into .whl packages. With this, we
should also be able to make the copyright headers in various files
more generalized.

Remove docutils dep in tox dist testenv

Now that we're using `twine check` to validate the package long
description, we no longer need to preinstall docutils in
testenv:dist.

Switch to `twine check` in tox testenv:dist

As of twine 1.12.0 we can now replace `setup.py check ...` with
`twine check` as a more standard approach to validating the markup
of description text in packages (and potentially other aspects of
package metadata in the future).

Add debug logging for Telnet protocol negotiation

For improved debugging of Telnet protocol negotiations, add a log
function wrapper to the telnet module and apply it any time Telnet
commands are received or sent.

Expand logging for User class methods

Increase logging detail so that client connection/disconnection,
account login/logout, avatar activation/deactivation and
creation/deletion can be clearly associated and followed for ease of
troubleshooting.

Support clients using CR+NUL to signal EOL

IETF RFC 854 requires that a Telnet server accept CR+NUL
interchangeably with CR+LF to indicate end of an input line from any
NVT (client). CR+NUL also happens to be the default behavior of
popular Telnet clients specifically when communicating on TCP port
23 (as opposed to non-default ports where more liberal protocol
fallbacks get employed). Previously these clients would need to `set
crlf` in their .telnetrc or at a telnet> command prompt as a
workaround.

Alter the selftest framework to send \r\0 from the NVT as an EOL to
make sure this does not regress, and add a test to explicitly end a
command with a \r\n just to make sure we can continue to support
CR+LF from clients.

Add a "debug" testenv

Create a convenience tox testenv named "debug" which simply starts
the mudpy service with the daemon test configuration, for use in
manual client testing.

Streamline selftest output

The standard output from a selftest run is much more brief, with the
prior verbose information redirected to a capture_tests.log file.

Clean up leading space typo in test title

This is merely a cosmetic fix removing stray leading whitespace from
a test's title.

Drop Python 3.3 support

Since wheel 0.30 and later no longer works with Python 3.3, it's
increasingly hard to test. Very few old platforms are likely to lack
Python 3.4 or later so this is a relatively safe move.

Also clean up some 3.3 workarounds as they're no longer needed if we
don't support running on it.

Add signed artifact URL to Python package metadata

As PyPI doesn't support serving detached signatures for sdist and
wheel packages, but we provide some, link the URL to our copies in
the package metadata so that it appears in the links on the PyPI
project page.

Clean up tox.ini

Remove an unused testenv:venv definition from tox.ini, and clean up
an unneeded ignore for .venv when running flake8.