Package: plm-dgraham
Player Lineup ManagerHistorySome variant ofplmhas been used privately since 2014 to schedule tennis doubles matches for a group of around 30 tennis players. Play for this group occurs weekly on Tuesdays using as many courts as necessary and the schedules are made for three months (one quarter) at a time. More recently, smaller Monday and Friday groups have been added each using at most one court. The process involves these steps.Obtain from each player a list of the dates that the player can play.Randomly sort available players for each date into groups of two (singles) or four (doubles) taking account of previous pairings.From each group, randomly select a 'captain' taking account of previous selections.Produce a "user friendly" version of the schedule organized both by date and by player.Send the completed schedule to each player.The current version of this program automates each of the steps in this process and allows some flexibility in scheduling dates, indicating a willingness to be a possible substitute, specifying the number of players per court (doubles or singles), and so forth. A further change is that all information relevant to a project is now stored in a single, project file inyamlformat with players's responses listing the dates that the playercanplay rather than the dates the playercannotplay. A final change is thatplmis now publically available both fromPyPi,plm-dgraham, and fromGitHub,dagraham/plm-dgraham.RequirementsThis program requirespython3. To check for this requirement, open a terminal window and execute:~ % which python3Ifpython3is installed the response should be something like/Library/Frameworks/Python.framework/Versions/3.10/bin/python3and, otherwise,python3 not foundIfpython3is not installed, follow the appropriate installation procedure for your platform.Initial SetupIfpython3is installed, the next step is to setup ahome directoryforplmto use when it starts. These are the options:If the current working directory contains a file 'roster.yaml' and a directory 'projects', then it will be used as thehome directory.Otherwise if the environmental variable 'plmHOME' is set and points to a directory, then that directory will be used as thehome directory.Otherwise~/plmwill be used as thehome directoryand, with your permission, created if it does not already exist.Whenplmis started for the first time, a sub-directory calledprojectsand a file calledroster.yamlwill be created in thehome directoryif they do not already exist.InstallationFor personal useThe easiest way to installplmfor personal use is to usepip. First update the python package manager,pip, using python3~ % python3 -m pip install -U pipand then installplmitself~ % python3 -m pip install -U plm-dgrahamThis will installplmand any needed supporting python modules. This same can also also be used to updateplmwhen a new version becomes available.For use in an isolated environment {#For-use-in-an-isolated-environment}Installing plm in an isolated or virtual environment (sandbox) is only slightly more complicated. Begin by usingpipto installpipx:$ python3 -m pip install -U pipxNow run:$ pipx ensurepathto ensure that directories necessary forpipxoperation are in your PATH environment variable and finally to installplmitself:$ pipx install plm-dgrahamTo upgradeplmwhen a new version becomes available, simply replace "install" in this command with "upgrade".StartingplmEither way, you can then startplmwith$ plm <path to home>and you will see something like thisPlayer Lineup Manager (0.3.4)
    home directory: ~/plm
    project: The active project has not yet been chosen.
    Use command 'c' to create one or 'p' to select one.

    commands:
        h:  show this help message
        H:  show on-line documentation
        e:  edit 'roster.yaml' using the default text editor
        c:  create/update a project                           (1)
        p:  select the active project from existing projects  (1)
        a:  ask players for their "can play" dates            (2)
        r:  record the "can play" responses                   (3)
        n:  nag players to submit can play responses          (4)
        s:  schedule play using the "can play" responses      (5)
        d:  deliver the schedule to the players               (6)
        v:  view the current settings of a project
        u:  check for an update to a later plm version
        q:  quit

    command:This begins a loop in whichplmwaits for you to enter a command at the prompt, processes the command and, unless the commandq(quit) is given, waits for your next command.Note: the commandsa,r,s,dandvbegin with a request that you select theactive projectif you have not already done so with eithercorp. Tab completion is available and, once a selection is made, this project becomes theactive projectfor any further use of the commands in this group while the command loop continues.The Player Directory: roster.yamlThis file is the directory for the players in all of your projects. It should be populated with all the relevant players for a project before you create the project itself.You can openroster.yamlin your favorite editor or use commande:command: eto haveplmopen the file for you. Each line in the roster file should have the formatlastname, firstname: [emailaddress,  tag1, tag2, ... ]For example:Doaks, Steve: [stvdoaks321@gmail.com, mon, tue]
    Smith, John: [jsmith123@gmail.com, tue, fri]
    ...When creating a new project, you will be prompted for the tag of the players to be included so that, in the above example, the tagmonwould include only Steve, but the tagtuewould include both Steve and John.It is worth devoting some thought to thetagscheme you will use before you start adding players. My schedules involve groups that play on a particular week day so I tend to use tags for the week day that the group plays, e.g.,monfor the group that plays onMonday. Note that tags are case sensitive somon,MonandMONare all different tags.A New Project From Start to Finish1. Create the project fileStartplm, if necessary, and use thecreate projectcommand:command: cThen follow the on-line prompts to enter the project information. This information will be stored in a new file in the projects directory,<project_name>.yaml, where<project_name>is the name you provide for the project. A short name that sorts well and is suggestive is recommended, e.g.,2022-4Q-TU.The value ofCANin the project settings affects both the request for player dates and the interpretation of the dates:WhenCAN == y(the default) the request is for a list of dates on which the playerCANplay.WhenCAN == nthe request is for a list of dates on which the playerCANNOTplay.2. Request player datesWith the project file created, the next step is to request the "CAN" or "CANNOT" play dates from the players (depending upon the setting forCAN). To do this startplm, if necessary, and use theaskcommand:command: aYou will be advised to open your favorite email application and create a new, empty email. You will then be prompted to select the relevant project. Tab completion is available to choose the project you created in the previous step. When you have selected the project, you will then be advised that the relevant email addresses have been copied to the system clipboard. Paste these into the "To" section of your new email and then pressreturninplmto continue. You will next be advised that the relevant subject has been copied to the system clipboard. Paste this into the "Subject" section of your email and again pressreturninplmto continue. You will finally be advised that the body of the request email has been copied to the system clipboard for you to paste into your email. When you are satisfied with the result, you can send the completed email.3. Enter player responsesAs you receive responses, you can startplm, if necessary, and use therecordcommand:command: rAgain you will be prompted to choose the relevant project with tab completion available. This begins a loop in which you can choose a player using tab completion and then enter the player's response to the dates request. The response for a player can be 'all', 'none', 'nr' (no response) or a comma separated list of dates using the month/day format. Asterisks can be appended to dates in which the player wants to be listed as a sub, e.g., '10/4, 10/18*, 10/25' for can or cannot play on 10/4 or 10/25 (depending uponCAN) and might be able to subsitute on 10/18. This process continues until you enter a 'q' to end the loop and, if changes have been made, indicate whether or not you would like to save them. This entry process can be repeated as often as you like until you are satisfied that all responses have been correctly entered.Hint: you can haveplmrunning in a terminal window near your email program with thercommand activated so that when you get a reply from say, Joe Smith, you can just enter "j" at the prompt to choose "Joe Smith" using auto completion and then enter his reply. This is handy because the replies will, at best, arrive sporadically.4. Process responses to create the scheduleStartplm, if necessary, and use theschedulecommand when you are satisfied that all player responses have been received and recorded.command: sAgain, you will be prompted to choose the relevant project using tab completion. The schedule will be processed and added to the project file without further input.5. Deliver the completed schedule to the playersThis step involves thedelivercommand.command: dAs with the process for requesting "can play" dates, this prompts for the relevant project and then successively copies 1) the email addresses, 2) the subject and 3) the schedule itself to the system clipboard so that each can be pasted in turn into an email to be sent to the relevant players.Modifying an existing projectYou might want to add a player to a project you've already created, update the email address of an existing player or make some other change to an existing project. To do this, first make any needed changes toroster.yamlusingcommand: eWhen adding new players or modifying the email addresses of existing players, the changes will be incorporated into an existing project in the next step. Also, any responses that have been recorded for existing players will be preserved in the next step. However, changing thenameof an existing player will effectivelydeletethe original player and thenaddthe new player. Any "can play" response you might have recorded in the project under the original name of the player would be lost in the process.When you've finished updatingroster.yaml, the next step is to use theprojectcommandcommand: pYou will again be prompted for the same information you entered when you first created the project, but this time your previous responses will be the defaults. With each prompt, you can simply pressenterto accept your original entry or make any changes you like and then pressenterto update the entry. When you have finished with each of the prompts, you will be asked for a final confirmation before modifying the original project file. As noted above, any "can play" responses that had previously been recorded in the project will be preserved for players whose names have not been changed.