lyntin.exported

Package lyntin :: Module exported

[show private | hide private]

Module lyntin.exported

This is the API for lyntin internals and is guaranteed to change very rarely even though we might change Lyntin's internals. If it does change it'll be between major Lyntin versions.

write_hook:

  The write_hook allows you to persist data.  Functions that register
  with this hook should return a list of strings.

  For example, the alias plugin would register with this hook and if
  I had an alias vv, it would return:

     [ "alias {vv} {this is my alias}" ]

  as its data.  If quiet == 1, then it would return:

     [ "alias {vv} {this is my alias} quiet={true}" ]

  because "quiet" is an argument for the alias command which quells
  output when it's called (assuming the output isn't error output).

  Arg mapping: {"session": Session, "quiet": boolean }

  session - the session in question

  quiet - whether (1) or not (0) to append an argument that causes
          the command to quell input when it is later read in

Exceptions
`DoneSpammingException`
`StopSpammingException`	This is what you raise when you're implementing a handler hook and you've handled the data.

Function Summary
	`add_command(cmd, func, arguments, argoptions, helptext)` This function allows you to add additional commands to Lyntin.
	`add_config(name, configitem, ses)` Adds a new configuration item.
string	`add_help(fqn, helptext)` Adds a help topic to the structure.
	`add_manager(name, mgr)` Registers a manager with the engine.
string	`expand_ses_vars(text, ses)` Grabs the variable manager (which we're hoping is using the same expand_vars as what's registered--only time will tell) and expands variables using the variable manager and its varmap.
	`filter_mapper(x, y)` This is the mapping function to use for filter-style hooks.
	`filter_mapper_hook_spam(hookname, argmap, emptyfunc, donefunc)` This is a slightly optimized filter_mapper hook because it's used so often in the system.
list of session.Session's	`get_active_sessions()` Returns a list of the active sessions including the common one.
list of strings	`get_commands()` Returns a list of the existing commands in Lyntin.
	`get_config(name, ses, defaultvalue)` Gets a value for a config item.
session.Session	`get_current_session()` Returns the current session.
	`get_engine()` This is a helper function provided for backwards compatibility with older modules.
string	`get_help(fqn)` Retrieves a help topic via a fully qualified name.
list of strings	`get_history(count)` Retrieves the history as a oldest to youngest list of strings.
Hook	`get_hook(hookname)` If the hook exists, returns the hook.
manager.Manager	`get_manager(name)` Retrieves a manager from the engine.
int	`get_num_errors()` Returns the total number of errors Lyntin has had thus far.
session.Session	`get_session(name)` Returns a named session or None if the session doesn't exist.
tuple of (int, int, int)	`get_version()` Returns Lyntin's version number as a tuple.
list of strings	`get_write_data(ses, quiet)` Calls the write_hook and retrieves data from all the functions that have registered with the hook.
	`hook_register(hookname, func, place)` Registers a function with a hook.
map of output arguments	`hook_spam(hookname, argmap, mappingfunc, emptyfunc, donefunc)` Sends out input to all the registrants of a hook.
	`hook_unregister(hookname, func)` If the hook exists, unregisters the func from the hook.
	`lyntin_command(text, internal, session)` The best way of executing a Lyntin command as if the user had typed it.
	`query_done(x)` This is the done hook function to go with the query mapper for proper behaviour.
	`query_mapper(x, y)` This is the mapping function to be used for query-style hooks.
boolean	`remove_command(text)` Removes a command from Lyntin.
	`remove_config(name, ses)` Allows you to remove a configuration item from the system.
	`remove_help(fqn)` Removes a help topic from Lyntin.
boolean	`remove_manager(name)` Removes a manager from the engine.
	`set_current_session(ses)` Changes the current session to another session.
	`set_num_errors(num)` Sets the number of errors Lyntin has had thus far.
	`tally_error()` This adds one to the current error count and checks to see if we're over our limit.
	`write_error(text, ses)` Calls engine.myengine.writeError which writes ERROR message.
	`write_message(text, ses)` Calls engine.myengine.writeMessage which writes LTDATA message.
	`write_mud_data(text, ses)` Calls engine.myengine.writeMudData which writes a MUDDATA message.
	`write_traceback(message, ses)` Convenience method for grabbing the traceback, formatting it, piping it through write_error, with a message for the user.
	`write_ui(text)` Calls engine.myengine.writeUI which writes a message to the ui.
	`write_user_data(text, ses)` Calls engine.myengine.writeUserData which writes a USERDATA message.

Variable Summary
`int`	`FIRST` = 1
`int`	`LAST` = 99
`NoneType`	`myengine` = None

Function Details

add_command(cmd, func, arguments=None, argoptions=None, helptext='')

This function allows you to add additional commands to Lyntin. Note, if you add a command that has the same name as an existing command, we'll first remove the existing command and then add the new command (this is done in the CommandManager).

If you add a ^ to the beginning of the command name, then the user has to type the entire command name for it to kick off. For example, if I specified "^end", then the user has to type "#end" to execute that command. If I had specified "end", then the user could type "e", "en", or "end".

If you don't specify helptext and the function has a doc_string, then we'll pull the helptext from the function's doc_string.

This creates a basic command that has no arguments or argoptions and adds it to the CommandManager:

 import os
 from lyntin.exported import add_command

 ht = "This command does an os.system("who") to let you see " +          "who's online\nright now."

 def who_cmd(ses, args, input):
   os.system("who")

 add_command("who", who_cmd, "", None, ht)

Same thing, but the help text is in the doc_string of the command:

 import os
 from lyntin.exported import add_command

 def who_cmd(ses, args, input):
   """
   This command does an os.system("who") to let you see who's
   online right now.
   """
   os.system("who")

 add_command("who", who_cmd)

Parameters:: cmd - the command name to add. ex. "help"
(type=string); func - the function to call to handle the command
(type=function); arguments - the argument spec for building the ArgumentParser
(type=string); argoptions - the options to give the ArgumentParser to tell it how to parse the arguments
(type=string); helptext - the helptext associated with this command to give to the HelpManager
(type=string)

add_config(name, configitem, ses=None)

Adds a new configuration item. Configuration items allow you to present the user with options that they can change which control the behavior of your module. Examples of this abound in Lyntin.

Here we create a boolean config item to control whether we're ignoring actions or not for the session named "a":

 from lyntin import config
 from lyntin.exported import add_config

 tc = config.BoolConfig("ignoreactions", 0, 1, "Allows you to turn off action handling")
 add_config("ignoreactions", tc, get_session("a"))

Parameters:: name - the name of the item
(type=string); configitem - the configuration item to add
(type=ConfigBase); ses - if this item is session based, then this is the session to associate the item with
(type=Session)

Raises:: ValueError - if there is already an item with that name for that session

add_help(fqn, helptext)

Adds a help topic to the structure. See the helpmanager documentation for more details as to what the helptext should look like.

Note: If you're building commands, the add_command function allows you to pass in help text for the command. If you don't pass in help text and the command function has a doc_string, then we'll try to extract the help text from the doc_string.

Parameters:: fqn - a . delmited string of categories ending with a help name
(type=string); helptext - the help text
(type=string)

Returns:: the fqn of where the help topic was stored (you can place category overrides in the helptext)
(type=string)

add_manager(name, mgr)

Registers a manager with the engine.

example of usage:

  from lyntin.exported import add_manager
  from lyntin import manager

  class MyManager(manager.Manager):
    def __init__(self):
      pass

  add_manager("mymanager", MyManager)

Managers are pretty straightforward especially considering that Lyntin makes great use of them so there are lots of examples.

Parameters:: name - the name of the manager to register with Lyntin
(type=string); mgr - the manager instance being registered
(type=manager.Manager)

expand_ses_vars(text, ses)

Grabs the variable manager (which we're hoping is using the same expand_vars as what's registered--only time will tell) and expands variables using the variable manager and its varmap.

Parameters:: text - the text to expand variables in
(type=string); ses - the session object to pass to the VariableManager
(type=session.Session)

Returns:: the text with variables expanded
(type=string)

filter_mapper(x, y)

This is the mapping function to use for filter-style hooks. Spamhook should be called as:

spamargs = {"session": ses, "data": data, "dataadj": data... }
spamargs = exported.hook_spam(... spamargs ...)
output = spamargs["dataadj"]

Each filter function will get a map with at least the following keys when it is called:

session - the session
data - the original data
dataadj - the adjusted data

filter_mapper_hook_spam(hookname, argmap={}, emptyfunc=<function <lambda> at 0x4025f924>, donefunc=<function <lambda> at 0x4025f95c>)

This is a slightly optimized filter_mapper hook because it's used so often in the system. It incorproates the filter_mapper, but skips any exception handling.

Arguments correspond to hook_spam.

get_active_sessions()

Returns a list of the active sessions including the common one.

Returns:: the list of active sessions
(type=list of session.Session's)

get_commands()

Returns a list of the existing commands in Lyntin.

Returns:: the list of commands currently registered with Lyntin
(type=list of strings)

get_config(name, ses=None, defaultvalue='No default value')

Gets a value for a config item. If the default value is not specified, then it will raise a ValueError.

This gets the snoopdefault config value. Since we're not specifying a session, it'll get the global one:

  from lyntin.exported import get_config

  snoopdefault = get_config("snoopdefault", defaultvalue=0)

This gets the ignoreactions setting for the session named "a":

  from lyntin.exported import get_config, get_session

  ia = get_config("ignoreactions", get_session("a"), defaultvalue=0)

Parameters:: name - the name of the item to retrieve the value of
(type=string); ses - the session (or None if this is not session-scoped)
(type=Session); defaultvalue - the value to return if there is no config item of that name. if you don't specify this, then we'll raise a ValueError.
(type=varies)

get_current_session()

Returns the current session.

Returns:: the current session
(type=session.Session)

get_engine()

This is a helper function provided for backwards compatibility with older modules.

get_help(fqn)

Retrieves a help topic via a fully qualified name.

Parameters:: fqn - a . delimited string of categories ending with a help name
(type=string)

Returns:: the help topic of that name or None if the topic doesn't exist
(type=string)

get_history(count=30)

Retrieves the history as a oldest to youngest list of strings.

Parameters:: count - the number of lines to return
(type=int)

Returns:: the history oldest to youngest
(type=list of strings)

get_hook(hookname)

If the hook exists, returns the hook. Otherwise it creates a new hook and returns that.

Parameters:: hookname - the name of the hook to retrieve
(type=string)

Returns:: the Hook by the name of hookname
(type=Hook)

get_manager(name)

Retrieves a manager from the engine.

Parameters:: name - the name of the manager to retrieve
(type=string)

Returns:: the manager instance
(type=manager.Manager)

get_num_errors()

Returns the total number of errors Lyntin has had thus far.

Returns:: the number of unhandled errors Lyntin has encountered so far
(type=int)

get_session(name)

Returns a named session or None if the session doesn't exist.

Parameters:: name - the name of the session to retrieve
(type=string)

Returns:: the session instance or None
(type=session.Session)

get_version()

Returns Lyntin's version number as a tuple. For example, if this were Lyntin version 4.0, the tuple would be (4, 0, 0). If this were Lyntin version 55.3.2 the tuple would be (55, 3, 2).

Returns:: the version number of this installation of Lyntin
(type=tuple of (int, int, int))

get_write_data(ses, quiet=0)

Calls the write_hook and retrieves data from all the functions that have registered with the hook. It passes in the session involved, and also the "quiet" argument.

For example, the alias module might have one alias for session a. It would return:

 [ "alias {vv %1} {evoke %1}" ]

If quiet was 1, then it would return:

 [ "alias {vv %1} {evoke %1} quiet={true}" ]

Then this method would take all those lists of strings and generate one list of all the strings and return it.

Exceptions kicked up by poorly written plugins (and bad Lyntin code) will get percolated upwards. i.e. if exceptions are raised, then you won't get any return data.

Parameters:: ses - the session to save the data for
(type=Session); quiet - whether or not to be quiet--this is for when the data that is written is eventually read in. 0 if not quiet, 1 if quiet.
(type=boolean)

Returns:: data as a list of strings
(type=list of strings)

hook_register(hookname, func, place=99)

Registers a function with a hook.

Parameters:: hookname - the name of the hook
(type=string); func - the function to register with the hook
(type=function); place - the function will get this place in the call order. functions with the same place specified will get arbitrary ordering. defaults to constants.LAST.
(type=int)

hook_spam(hookname, argmap={}, mappingfunc=<function <lambda> at 0x4025f844>, emptyfunc=<function <lambda> at 0x4025f87c>, donefunc=<function <lambda> at 0x4025f8b4>)

Sends out input to all the registrants of a hook.

Parameters:: hookname - the name of the hook to spam
(type=string); argmap - the map of arguments that gets passed to each function in the hook. the actual arguments differs from hook to hook.
(type=dict of arguments); mappingfunc - function whose output will be passed to the next function in the hook. Must take two arguments: the previous arglist and the return from the previous function.
(type=function); emptyfunc - Function to be called with arglist if there are no objects registered with this hook. Must take 1 argument, the arglist tuple, and return what spamhook should return.
(type=function); donefunc - Function to be called when spamming finishes normally. Should take 1 argument and return what spamhook should return.
(type=function)

Returns:: argmap
(type=map of output arguments)

hook_unregister(hookname, func)

If the hook exists, unregisters the func from the hook.

Parameters:: hookname - the name of the hook
(type=string); func - the function to remove from the hook
(type=function)

lyntin_command(text, internal=0, session=None)

The best way of executing a Lyntin command as if the user had typed it.

This executes "#help", doesn't create an entry in the history, and doesn't spam the from_user_hook:

 from lyntin.exported import lyntin_command
 lyntin_command("#help", internal=1, session=None)

This executes "#action {killing blow} {reclaim}", creates an entry in the history, spams the from_user_hook, and does it in the session named "a":

 from lyntin.exported import lyntin_command, get_session
 lyntin_command("#action {killing blow} {reclaim}", internal=0, session=get_session("a"))

Parameters:: text - the command to execute. ex. "#help"
(type=string); internal - whether (1) or not (0) to execute the line internally suppressing history and the spamhook.
(type=boolean); session - the session instance to execute this command in (defaults to the current session)
(type=Session)

query_done(x)

This is the done hook function to go with the query mapper for proper behaviour.

query_mapper(x, y)

This is the mapping function to be used for query-style hooks. Spamhook should be called as:

output = hook.spamhook( arguments )

Each hook function will be called with the arguments until one function returns non-None. That non-None value will be returned from spamhook

remove_command(text)

Removes a command from Lyntin.

Parameters:: text - the name of the command to remove
(type=string)

Returns:: 0 if no command was found, 1 if the command was removed successfully
(type=boolean)

remove_config(name, ses=None)

Allows you to remove a configuration item from the system.

Parameters:: name - the name of the item to remove
(type=string); ses - the session from which to remove the item (None if it's a general Lyntin item)
(type=Session)

Raises:: ValueError - if the item does not exist

remove_help(fqn)

Removes a help topic from Lyntin.

Parameters:: fqn - a . delmited string of categories ending with a help name
(type=string)

remove_manager(name)

Removes a manager from the engine.

Parameters:: name - the name of the manager to remove from Lyntin
(type=string)

Returns:: 0 if nothing happened, 1 if the manager was removed
(type=boolean)

set_current_session(ses)

Changes the current session to another session.

Parameters:: ses - the session instance to set the current session to
(type=session.Session)

set_num_errors(num)

Sets the number of errors Lyntin has had thus far. Do be careful when setting this because Lyntin keeps track of errors for the purposes of shutting down the client in case we get into a runaway exception loop.

Parameters:: num - the number of errors to set
(type=int)

tally_error()

This adds one to the current error count and checks to see if we're over our limit. If we are, it enqueues a shutdown event which will shutdown Lyntin.

write_error(text, ses=None)

Calls engine.myengine.writeError which writes ERROR message. If there is no engine instance available, it prints it to sysout.

Parameters:: text - the message to send
(type=string); ses - the session instance the error data is associated with
(type=session.Session)

write_message(text, ses=None)

Calls engine.myengine.writeMessage which writes LTDATA message. If there is no engine instance available, it prints it to sysout.

Parameters:: text - the message to send
(type=string); ses - the session instance the error data is associated with
(type=session.Session)

write_mud_data(text, ses=None)

Calls engine.myengine.writeMudData which writes a MUDDATA message. If there is no engine instance available, it prints it to sysout.

Parameters:: text - the message to send
(type=string); ses - the session instance the mud data is associated with
(type=session.Session)

write_traceback(message='', ses=None)

Convenience method for grabbing the traceback, formatting it, piping it through write_error, with a message for the user.

Parameters:: message - any message you want to pass to the user--this gets printed first
(type=string); ses - the session instance the mud data is associated with
(type=session.Session)

write_ui(text)

Calls engine.myengine.writeUI which writes a message to the ui. If there is no engine instance available, it prints it to sysout.

Parameters:: text - the message to write to the ui
(type=string or ui.Message)

write_user_data(text, ses=None)

Calls engine.myengine.writeUserData which writes a USERDATA message. If there is no engine instance available, it prints it to sysout.

Parameters:: text - the message to send
(type=string); ses - the session instance the user data is associated with
(type=session.Session)

Variable Details

FIRST

Type:: int
Value:: 1

LAST

Type:: int
Value:: 99

myengine

Type:: NoneType
Value:: None

Generated by Epydoc 2.1 on Mon Aug 9 09:17:42 2004

http://epydoc.sf.net