Package: winsys
Enter WinSys: the Python Windows Administrator’s Toolkit. A collection
of modules with a consistent approach, wrapping the Windows API
calls already exposed by pywin32, adding some with ctypes, and giving them
all a pythonic feel. There’s nothing here you couldn’t do yourself with
10 minutes and a copy of the pywin32 and SDK docs. But it’s all here already,
and with a more Pythonish feel about it.Docs available at:http://winsys.readthedocs.org/en/latest/index.htmlDesign PrinciplesThe following principles have directed the design of the modules
and packages wherever possible:Make ad-hoc use possible and easy (and even attractive)Provide sensible defaults for the common cases, always allowing for more complex scenariosPut all constants into one place, grouping them according to their API usageUse the pywin32 functionality where available, supplementing it with ctypes where neededAssume a recent version of Python (tested on 2.6, 2.7, 3.2, 3.3)Make good use of context managers (with-statements)Have each object able to dump its contents and that of its children cleanlyMaintain an object approach, but provide convenient module-level functionsHave useful factory functions for classes, robustly accepting string or object parametersCommon FeaturesMost of the objects in winsys subclass thecore._WinSysObjectclass which
offers sensible defaults and defines common functionality such as a dump function.
In addition, the following features are common to many of the modules:Pythonic NamingThis is mildly contentious, but the same naming convention has been used
throughout, following thelowercase_with_underscoresconvention widely
adopted in the Python community. The most widespread exception to this is
in theconstantsmodule, where Windows constants retain theirUPPERCASE_WITH_UNDERSCORESnames.Module-level FunctionsWhile a lot of use has been made of Python classes to wrap the function-driven
Windows API, a lot of the functionality has been exposed as module-level
convenience functions. So, for example, in thefsmodule, thefs.Fileclass offers afs.File.copymethod, but the same functionality is exposed
at the module level asfs.copy. That way, you don’t have to instantiate
one or more objects simply for the purpose of a single operation.Factory FunctionsMost of the classes have a corresponding factory function (usually with
the same name in lower case) which tries to be more accepting in what
its parameters are and to convert them to what’s needed by the class’s
own__init__method. So, for example, thePrincipalclass whose
initialiser expects a PySID structure has a correspondingprincipalfunction which will take a Sid or a user or group name or None or an existingPrincipalobject.DumpEach object derived fromcore._WinSysObjecthas a dump method which
is intended to display its internal structures, possibly recursively where
some of the structures are themselves WinSys objects. This is intended more
for ad-hoc use in the interpreter where it’s convenient to see, eg, the
security structure which has been loaded from a file.Iterators & GeneratorsWhere possible and meaningful, lazy iterators have been used, often
implemented by generators. This started in thefsmodule where
thousands of files were being queried for information, but the approach
has generally been adopted across the package.Context ManagersWhere it makes sense, context managers have been used, either by means
of the contextlib contextmanager decorator or by defining an object as
its own context manager by means of__enter__and__exit__methods.
Examples of context-managed objects include theipc.Mailslotandsecurity.Securityobjects. Examples of decorated functions include
thesecurity.change_privilegesandsecurity.impersonatefunctions.ToDoObviously, there’s loads to do. The Windows API is vast; even the amount of
it exposed by pywin32 far exceeds my immediate needs and the time at my
disposal. The implementation of this package has been driven largely by the
very specific needs of our Windows sysadmins in their day-to-day work. My
intention is to carry on wrapping Windows functionality in a similar way,
but if anyone has particular needs, or can provide functionality to add in,
let’s hear about it.