Task: Rename a Project with a Python Script

• Permissions Required
• Other Requirements
• The Renaming Script
• Using the Script
• Modifying the Script
• Writing Other Scripts
• Running Scripts Automatically
• Links

Permissions Required

The script requires that special user Anonymous has the following permissions for the project P of interest.

• PROJECT_READ P
• PROJECT_WRITE P

If you will be extending the script to derive the project ID from an analysis directory for some analysis A of the project, you will also need the following permissions for A.

• ANALYSIS_READ A

See Modifying the Script for information on modifying the script to specify credentials for a non-Anonymous user with the required permissions.

Other Requirements

The Renaming Script

The following script will change the name of

• the project whose project ID matches the second argument passed to the script,
• on the hub specified in the first argument to the script,
• to the value specified in the third argument to the script.

import argparse
import os
import re
import subprocess

def rename_project(hubaddr, project_id, newname):
    curl_cmd = ['curl']
    def check_page(inarg):
        args = ['-o', os.devnull, '-w', '%{http_code}']
        if isinstance(inarg, str):
            args = args + [inarg]
        else:
            args = args + inarg
        http_code = subprocess.check_output(curl_cmd + args)
        return (int(http_code.strip())==200)

    project_html_url = '{0}/project/{1}.html'.format(hubaddr,project_id)

    # Download and scrape Project HTML page for old_name_hash
    project_dl=subprocess.Popen(curl_cmd + [project_html_url],
                                stdout=subprocess.PIPE)
    project_page=project_dl.communicate()[0].decode()

    onh_match=re.search(r'<input\s+type="hidden"\s+id="old_name_hash"\s+name="old_name_hash"\s+value="((-?)\d+)">',
                        project_page)

    if onh_match is None:
        print('Could not get project page', project_html_url)
        print('Make sure you have PROJECT_READ permission for this project.')
        exit(1)

    
    # Attempt to rename the project; check the HTTP response code.
    rename_arguments = ['-d', 'old_name_hash={0}'.format(onh_match.group(1)),
                        '-d', 'new_name={0}'.format(newname),
                        project_html_url]
    if not check_page(rename_arguments):
        print('Could not rename project {0}'.format(project_id))
        print('Make sure you have PROJECT_WRITE permission for this project.')
        exit(1)

    # Fetch and output the updated Project page on success.  This is
    # not necessary and can be commented out: it just ensures that
    # the script outputs the updated page as specified in the Task description.
    subprocess.check_call(curl_cmd + [project_html_url])


# Set up. 
def go():
    parser = argparse.ArgumentParser(
        description=('Rename a project on a CodeSonar hub, '
                     + 'as specified by the command-line arguments.'))
        
    parser.add_argument("hub",
                        help="The hub URL.")
    parser.add_argument("pid",
                        help="The project ID of the project to rename")
    parser.add_argument("newname",
                        help="The new project name; must be URL-encoded.")
    args = parser.parse_args()

    allargs = (args.hub, args.pid, args.newname)
    if not any([a is None for a in allargs]):
        rename_project(*allargs)

go()

This Python script uses an HTTP POST request to send the new project name to the hub, just as the web form on the Project page would do if you were changing the name in the web GUI. It outputs the updated Project page HTML.

Note that the HTTP POST request must include both the new project name (new_name) and CodeSonar's hash of the current project name (old_name_hash). The CodeSonar hub requires the hash value as a consistency check, so the script must recover it from a separate initial page request.

Using the Script

To use this script with your hub, do the following.

1. Copy rename_project.py to a suitable directory. The remainder of these instructions will refer to this directory as rundir.
2. Run the script:
   cd rundir
   python rename_project.py protocol://host:port pid newname
   where

   protocol	is the protocol for your hub: http or https.
   host:port	is the location of your hub.
   pid	is the project ID for the project whose name you wish to change. You can find the project ID: in the GUI Project page URL, which will be of the form http://hub_location/project/project_id.html, or by deriving it based on the analysis ID from the most recent analysis of the project, which in turn is available: in the URL specified at the end build/analysis command output, which will be of the form http://hub_location/analysis/analysis_id.html, or by running the following command, where path/to/projname.prj_files/ is the analysis directory codesonar analysis_id.py path/to/projname.prj_files/ or in file path/to/projname.prj_files/aid.txt, where path/to/projname.prj_files/ is the analysis directory. For details, see Derive the project ID from the analysis directory, below.
   newname	is new name you wish to set for the project. It must be URL-encoded.

   The script will output information about its progress.
3. Open the project page protocol://host:port/project/pid.html in your web browser to confirm that its name has changed (or look at the top of the output).

Invocation Example

Using the hub at http://[::1]:7341, change the name of the project with ID 3 to "My Renamed Project ":

• Note the URL-encoding of the new name.

Troubleshooting

curl_cmd=['curl', '-v']

Modifying the Script

You may wish to make one or more of the following modifications.

• Stop printing the updated HTML file to output
• Derive the project ID from the analysis directory
• Provide credentials for a non-Anonymous user

Stop printing the updated HTML file to output

If you don't want to see the updated HTML file as part of your script's output, you can redirect it to the null location by modifying your curl command. Note that if you make further changes that you need to debug later, you may wish to lift this suppression at least temporarily.

1. Edit rename_project.py to comment out the last line of code in function rename_project().

Derive the project ID from the analysis directory

Instead of specifying the project ID on the command line, you can change the script to read the analysis directory from the command line and derive the project ID by reading the most recent analysis ID from the analysis directory, requesting the corresponding Analysis page from the hub, then reading the project ID from the Analysis page.

Because this approach requires the Analysis page for the analysis A in question, you must have the following permissions for A in addition to the required project permissions.

• ANALYSIS_READ A

Once you have verified that you have these permissions, proceed as follows.

1. In function go(), replace line

   parser.add_argument("pid", help="The project ID of the project to rename.")

   with a line adding an adir argument.

   parser.add_argument("adir", help="The analysis .prj_files directory.")
   

2. In function go(), change the definition of allargs to:

   allargs = (args.hub, args.adir, args.newname)
   

3. Modify the rename_project() function header, and add two new lines to the very beginning of the function definition.

   def rename_project(hubaddr, analysis_dir, newname):
       with open(os.path.join(analysis_dir,'aid.txt'),'r') as aidfile:
           analysis_id=aidfile.read()
   

4. Insert the following code after the definition of check_page() and before the line setting project_html_url.

       analysis_html_url = f'{hubaddr}/analysis/{analysis_id}.html'
   
       # Download and scrape Analysis HTML page for a project ID,
       # which will be that of the analyzed project.
       analysis_dl=subprocess.Popen(curl_cmd + [analysis_html_url],
                                   stdout=subprocess.PIPE)
       analysis_page=analysis_dl.communicate()[0]
       pid_match=re.search(r'<a href="/project/(\d+).html">',
                           analysis_page)
       if pid_match is None:
           print 'Could not get analysis page', analysis_html_url
           print 'Make sure you have ANALYSIS_READ permission for this analysis.'
           exit(1)
   
       project_id = pid_match.group(1)
   

5. When you invoke the script, specify the analysis directory as the second argument.

   For example: using the hub at http://[::1]:7341, rename the project analyzed in directory whose /myprojects/projectX.prj_files/ to "Another Renamed Project".

   python rename_project.py http://[::1]:7341 /myprojects/projectX.prj_files/ Another%20Renamed%Project

Provide credentials for a non-Anonymous user

If your hub is configured so that special user Anonymous does not have the required permissions, you will need to edit the script to submit credentials for a suitable hub user account.

See CodeSonar HTTP API: Authentication for more information on authentication strategies.

Running Scripts Automatically

You can use your system tools to arrange for the Python script to be run automatically.

5 2 * * * python /path/to/rename_project.py http://red:7341 2 My%20New%20Name

Links

• Typical CodeSonar Tasks
• HTTP API Documentation
• The CodeSonar Hub
• CodeSonar GUI Reference