            ReadMe for p4lib.py and 'px'.

==== Table of Contents

Introduction
Install Notes
Changelog
Known Bugs
TODO list/Feature Requests



==== Introduction

Perforce is a source code control system (like CVS). One uses the p4
command line application (and/or a GUI client) to work with a Perforce
repository. px is a wrapper around p4. It provides all the functionality
of p4 (defering work to it) plus it extends some standard p4 commands
and adds a few new ones. If you are a Perforce user you might find these
extensions useful.

px uses p4lib.py, a Python interface to the Perforce client application.
If you are a Python programmer and script Perforce you might find this
module helpful. Currently, most common commands (though your definition
of "common" may differ from mine) are supported.



==== Install Notes

1. Download the latest 'px' package for your platform from
   http://starship.python.net/~tmick.
2. Unpack the package in a temporary directory.
3. Run 'python setup.py install' in the created px-<version> directory.



==== Changelog

v0.7.2:
    - Avoid a possible hang when running commands use "*" in the
      filespec. See test/test_hang.py for details.
    - Change _raw output to return unsplit output.

v0.7.1:
    - Add '_raw' option to each P4 command to change the return value to
      be the unprocessed results from running p4.

v0.7.0:
    - (BACKWARD INCOMPATIBILITY) Drop 'optv' method of passing p4
      options to P4 constructor.  Instead use named keyword args. Also
      add optional keyword args to every P4 command to allow overriding
      the instances p4 options for a specific command.
      This may break p4lib.P4() usage. To quickly convert one may use
      this pattern: Change usages of:
        p4lib.P4(<optv argument>)
      to
        p4 = p4lib.P4( **p4lib.parseOptv(self.__p4optv) )

v0.6.8:
    - Add interfaces in p4lib.py to 'p4 label', 'p4 labels', 'p4 flush',
      'p4 branch', 'p4 branches'.
    - Fix bug in p4lib.py interface to 'p4 have' where files containing
      " - " could not be handled.

v0.6.7:
    - Add interface to 'p4 client' and 'p4 clients' in p4lib.py.
    - Fix bugs in 'px genpatch' where opened files without changes or
      non-existant added files could not be handled.

v0.6.6:
    - first public release



==== Known Bugs

See Bugs.txt.



==== TODO list/Feature Requests

General TODOs:
- Search for "TODO" in all source files, including in the test suite
  files.
- Run pydoc over my p4lib.py and put that up on the release site. Will
  have to clean it up a little bit. (pydoc is *not* polished.)

px TODO's:
- extend the logging with '*args' as in p4lib.py
- px applypatch
- 'px genpatch' mechanism to limit the area, e.g. 'px genpatch ./...'
- px integrate??? (the p4x interface is kind of sucky)
- Perhaps some way to note integrations that I care about and display
  what changes need to be integrated where. Dunno if that is
  reasonable.
- perhaps some command to help clean up old dead changelists,
  clientviews and changelists
- adhere to 'p4 -s ...' in all output (blue sky)
- make sure -G works with all commands (it is currently broken:
  'px -G changes -d ./...'
- add a '-a' option to 'p4 set' to dump the chain of settings and
  perhaps some of the prose from the Tech Note describing how p4
  config values are determined. The *reporting* parts of this could
  be useful on Unix as well. I don't know that I want to get into
  the business of *setting* cfg vars on Unix.
- Perhaps determine if there are some useful merge algorithms that
  could be fit into either P4MERGE usage or by extending the -a
  options to 'p4 resolve'.
- px annotate:
    - The -i option tells annontate to follow branches.
    - perhaps add a --html option to output something suitable
      for browser viewing
    - perhaps add a way to return the dictionary object
- (Blue sky) an installer for 'px' that siloes Python. Perhaps this is
  overkill but it would be nice to not have to worry about it. Perhaps
  this is easy using McMillan's Installer or the other one.

p4lib.py TODO's:
* Add test cases for the _raw arguments to each method.
- Clean up p4options and _p4run usage. The commands using 'p4 -G' do not
  cleanly abstract p4options overriding. This should probably come in a
  wholesale conversion to using 'p4 -G' for all commands. Then a
  convenient abstraction of p4options overriding can be setup.
- .sync() test suite
- Rationalize what None or [] means for 'files' arguments. Take
  .submit() and .change() for example, the meaning varies. This
  should be, if possible, made common. May need a "NotSelected"
  default optional value that is not None.
- Redo the current command docstring to show, primarily how *p4lib*
  is used, rather than how a given p4lib command maps to the equiv
  'p4' command line command.
- a lot of commands:
    admin, branch, branches,
    client, clients, counter, counters, depot, depots, 
    dirs, fix, fixes, flush, fstat, group, groups, help?, info*,
    integrate, integrated, job, jobs, jobspec, label*, labels*,
    labelsync*, lock, logger, obliterate, passwd, protect, reopen*,
    resolved*, review, reviews, set,
    triggers, typemap, unlock, user, users, verify
- Make a mainline interface to this to mimic the p4 command line.
  This would be extremely useful for debugging and testing it.
  No real way to make the command line option -> optional func args
  mapping.
- The 'job' stuff: job, jobs, fix,fixes, jobspec, -s options on
  submit and change (at least)

