Changeset 116

Show
Ignore:
Timestamp:
07/29/06 17:43:03 (2 years ago)
Author:
mk
Message:

Updated README.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • branches/mk/README

    r52 r116  
    1212 
    1313 * whether the package can be downloaded from PyPI given its name 
    14  * whether the package can be downloaded from a full URL 
    1514 * whether the package can be unpacked 
    16  * whether the unpack directory is the same as the package name 
    1715 * whether the package can be installed into an alternate directory 
    1816 * existence of certain files such as README, INSTALL, LICENSE, setup.py etc. 
    19  * existence of certain directories such as doc, test, demo, examples 
    2017 * percentage of modules/functions/classes/methods with docstrings 
    21  * percentage of functions/methods that are unit tested (not currently  
    22    implemented) 
    23  * average pylint score for all non-test and non-demo modules 
     18 * ... and many others 
    2419 
    2520Currently, the Cheesecake index is computed for invidual packages obtained  
    …… 
    7469 
    7570If the package can be successfully downloaded and unpacked, a log file is 
    76 created in the sandbox directory and named <package>.log (e.g. the log file  
    77 for twill-0.7.4.tar.gz is /tmp/cheesecake_sandbox/twill-0.7.4.tar.gz.log). 
    78 The log file is not automatically deleted after the Cheesecake index is 
    79 computed, since its purpose is to be inspected for debug information. 
     71created in the system /tmp directory and named <package>.log (e.g. the log file  
     72for twill-0.7.4.tar.gz is /tmp/twill-0.7.4.tar.gz.log). 
     73The log file is automatically deleted after the Cheesecake index is 
     74computed, except for situations when error has occured. 
    8075 
    8176Command-line examples: 
    …… 
    10196------------------------- 
    10297 
    103 There is no release for Cheesecake yet, but you can get the source code via svn:: 
     98You can get the source code via svn:: 
    10499 
    105100  svn co http://svn.pycheesecake.org/trunk cheesecake 
    …… 
    138133http://www.opensource.org/licenses/PythonSoftFoundation.php. 
    139134 
    140 Author contact info 
    141 ------------------- 
     135Authors contact info 
     136-------------------- 
    142137 
    143138Grig Gheorghiu 
    …… 
    154149-------------------------------------------- 
    155150 
    156 The cheesecake.py module uses the following constants:: 
    157  
    158  INDEX_PYPI_DOWNLOAD = 50 
    159  INDEX_PYPI_DISTANCE = 5 
    160  INDEX_URL_DOWNLOAD  = 25 
    161  INDEX_UNPACK        = 25 
    162  INDEX_UNPACK_DIR    = 15 
    163  INDEX_INSTALL       = 50 
    164  INDEX_FILE_CRITICAL = 15 
    165  INDEX_FILE          = 10 
    166  INDEX_FILE_PYC      = 20 
    167  INDEX_DIR_CRITICAL  = 25 
    168  INDEX_DIR           = 20 
    169  INDEX_DIR_EMPTY     = 5 
    170  
    171  MAX_INDEX_DOCSTRINGS = 100 # max. percentage of modules/classes/methods/functions with docstrings 
    172  MAX_INDEX_PYLINT     = 100 # max. pylint score 
    173  
    174 **Step 0** 
    175  
    176 Initialize the Cheesecake index to 0. Also initialize to 0  
    177 the partial Cheesecake indexes for installability, documentation  
    178 and code kwalitee. 
    179  
    180 Compute the maximum overall Cheesecake index that can be reached by  
    181 any given package, which is the sum:: 
    182  
    183  INDEX_PYPI_DOWNLOAD +  
    184  INDEX_UNPACK + INDEX_UNPACK_DIR +  
    185  INDEX_INSTALL + 
    186  MAX_INDEX_DOCSTRINGS + MAX_INDEX_PYLINT +  
    187  (INDEX_FILE * number_of_expected_files) + 
    188  (INDEX_FILE_CRITICAL * number_of_expected_critical_files) + 
    189  (INDEX_DIR * number_of_expected_dirs) + 
    190  (INDEX_DIR_CRITICAL * number_of_expected_critical_dirs) 
    191  
    192 Compute the maximum Cheesecake index for installability, which is the sum:: 
    193  
    194  INDEX_PYPI_DOWNLOAD +  
    195  INDEX_UNPACK + INDEX_UNPACK_DIR +  
    196  INDEX_INSTALL 
    197  
    198 Compute the maximum Cheesecake index for documentation, which is the sum:: 
    199  
    200  (INDEX_FILE * number_of_expected_files) + 
    201  (INDEX_FILE_CRITICAL * number_of_expected_critical_files) + 
    202  (INDEX_DIR * number_of_expected_dirs) + 
    203  (INDEX_DIR_CRITICAL * number_of_expected_critical_dirs) + 
    204  MAX_INDEX_DOCSTRINGS 
    205  
    206 Compute the maximum Cheesecake index for code kwalitee, which is currently:: 
    207  
    208  MAX_INDEX_PYLINT 
    209  
    210 **Step 1a** 
    211  
    212 If short name of the package was specified with ``-n`` or ``--name``,  
    213 try to download the package from the PyPI index page by following the links to  
    214 the package home page and the package download URL (this is accomplished  
    215 using setuptools utilities). 
    216  
    217 If not successful, exit with a Cheesecake index of 0. If successful and  
    218 package was found at the Cheese Shop, add ``INDEX_PYPI_DOWNLOAD`` to  
    219 the overall Cheesecake index and to the installability Cheesecake index. 
    220  
    221 If successful but package was not found at the Cheese Shop, add  
    222 ``INDEX_PYPI_DOWNLOAD - (INDEX_PYPI_DISTANCE * number_of_links_to_package)`` 
    223 to the overall Cheesecake index and to the installability Cheesecake index. 
    224  
    225 **Step 1b** 
    226  
    227 If full URL of the package was specified with ``-u`` or ``--url``,  
    228 try to download the package from the specified URL. 
    229  
    230 If not successful, exit with a Cheesecake index of 0. If successful,  
    231 add ``INDEX_URL_DOWNLOAD`` to the overall Cheesecake index and to  
    232 the installability Cheesecake index. 
    233  
    234 **Step 1c** 
    235  
    236 If path to package on local file system was specified with ``-p`` or 
    237 ``--path``, copy the package to the sandbox directory. 
    238  
    239 **Step 2** 
    240  
    241 Unpack the package (currently supported archive types are zip and  
    242 tar.gz/tgz; in the near future we will support Python Eggs.) 
    243  
    244 If not successful, exit with a Cheesecake index of 0. If successful, add  
    245 ``INDEX_UNPACK`` to the overall Cheesecake index and to the installability  
    246 Cheesecake index. 
    247  
    248 **Step 3** 
    249  
    250 Check that the unpack directory has the same name as the package name 
    251 (i.e. when unpacking twill-0.7.4.tar.gz, we expect the unpack directory  
    252 to be twill-0.7.4.) 
    253  
    254 If the unpack directory name is the same as the package name, add  
    255 ``INDEX_UNPACK_DIR`` 
    256 to the overall Cheesecake index and to the installability Cheesecake index. 
    257  
    258 **Step 4** 
    259  
    260 Install the package to a temporary directory in a non-default location.  
    261 If successful, add ``INDEX_INSTALL`` to the overall Cheesecake index and to the 
    262 installability Cheesecake index. 
    263  
    264 **Step 5** 
    265  
    266 Check for existence of specific files.  
    267 For each file found, add ``INDEX_FILE`` to the overall  
    268 Cheesecake index and to the documentation Cheesecake index.  
    269 If the file is deemed critical, add ``INDEX_FILE_CRITICAL`` instead. 
    270  
    271 The following special files ("cheese_files") are currently checked:: 
    272  
    273     cheese_files = ["install", "changelog", 
    274                     "news", "faq", 
    275                     "todo", "thanks", "announce", 
    276                     "ez_setup.py", 
    277                    ] 
    278  
    279 The following files are currently deemed critical:: 
    280  
    281     critical_cheese_files = ["readme", "license", "setup.py"] 
    282  
    283 To check if a file FILE is among the cheese files, the following regular 
    284 expression is used:: 
    285  
    286     re.search(r"^%s(\.txt)*" % cheese_file, file, re.IGNORECASE) 
    287  
    288 **Step 6** 
    289  
    290 Check for existence of specific directories.  
    291 For each directory found, add ``INDEX_DIR`` to the overall Cheesecake  
    292 index and to the documentation Cheesecake index.  
    293 If the directory is deemed critical, add ``INDEX_DIR_CRITICAL`` instead. 
    294 If the directory is found empty, add ``INDEX_DIR_EMPTY`` instead. 
    295  
    296 The following directories ("cheese_dirs") are currently checked:: 
    297  
    298     cheese_dirs = ["example", "demo"] 
    299  
    300 The following directories are currently deemed critical:: 
    301  
    302     critical_cheese_dirs = ["doc", "test"] 
    303  
    304 To check if a directory DIR is among the cheese directories,  
    305 the following regular expression is used:: 
    306  
    307     re.search(r"^%s" % cheese_dir, DIR, re.ignorecase) 
    308  
    309 **Step 7** 
    310  
    311 Check for existence of .pyc files. If found, decrease the score  
    312 by subtracting ``INDEX_FILE_PYC`` from the overall Cheesecake index  
    313 and from the documentation Cheesecake index. 
    314  
    315 **Step 8** 
    316  
    317 Compute the percentage of modules/classes/methods/functions that have  
    318 docstrings associated with them. Only Python modules that are not in test,  
    319 doc, demo and example directories are checked.  
    320 Round up the percentage and add it to the overall Cheesecake index and to the 
    321 documentation Cheesecake index. 
    322  
    323 **Step 9** 
    324  
    325 If pylint is present on the system, run pylint against all Python files  
    326 that are not in the test, docs or demo directories.  
    327 Average the non-negative pylint scores, multiply the average by 10 and  
    328 add it to the overall Cheesecake index and to the code kwalitee  
    329 Cheesecake index. 
    330   
    331 **Step 10** 
    332  
    333 For each of the partial Cheesecake index types (installability,  
    334 documentation and code kwalitee), display the absolute Cheesecake  
    335 index for that type as the sum of all indexes of that type computed in  
    336 the previous steps.  
    337 Also display the relative Cheesecake index for that type as the percentage 
    338 of ``(absolute_index / maximum_index)``. 
    339  
    340 Display the absolute Cheesecake index for the package as the sum of all 
    341 indexes computed in the previous steps. Also display the relative Cheesecake 
    342 index for the package as the percentage of ``(absolute_index / maximum_index)``. 
     151Overall Cheesecke score is a sum of values of 3 main indexes 
     152(installability, documentation and code kwalitee). Values of these 
     153indexes rely on values of their subindexes and so on. Whole index tree 
     154and corresponding values for each leaf is presented below: 
     155 
     156* Installability 
     157 
     158  * package is listed on and can be downloaded from PyPI: 50 
     159  * package can be downloaded from given URL: 25 
     160  * package can be unpacked without problems: 25 
     161  * unpacked package directory is the same as package name: 15 
     162  * package has setup.py: 25 
     163  * package can be installed to given directory via "setup.py install": 50 
     164  * package contain generated files, like .pyc: -20 
     165 
     166* Documentation 
     167 
     168  * package contain files listed below 
     169 
     170    * README: 30 
     171    * LICENCE/COPYING: 30 
     172    * ANNOUNCE/CHANGELOG: 20 
     173    * INSTALL: 20 
     174    * AUTHORS: 10 
     175    * FAQ: 10 
     176    * NEWS: 10 
     177    * THANKS: 10 
     178    * TODO: 10 
     179 
     180  * package contain directories listed below 
     181 
     182    * doc/docs: 30 
     183    * test/tests: 30 
     184    * demo/example/examples: 10 
     185 
     186  * code is documented by docstrings: 100 
     187  * docstrings have proper formatting (like epytext or reST): 30 
     188 
     189* Code Kwalitee 
     190 
     191  * package has high pylint score: 50 
     192  * package uses at least one of known unit test frameworks: 30 
     193 
     194Final score depends on how well package scores for all indexes 
     195listed above. Score is presented in absolute range (number of points) 
     196and relative (percent of gathered points compared to maximum). 
    343197 
    344198Sample output 
    …… 
    347201:: 
    348202 
    349  $ python cheesecake.py -n Durus 
    350  [cheesecake:console] Trying to download package durus from PyPI using setuptools utilities 
    351  [cheesecake:console] Downloaded package Durus-3.1.tar.gz from http://www.mems-exchange.org/software/durus/Durus-3.1.tar.gz 
    352  [cheesecake:console] Detailed info available in log file /tmp/cheesecake_sandbox/durus.log 
    353  [cheesecake:console] A given package can currently reach a MAXIMUM number of 555 points 
    354  [cheesecake:console] Starting computation of Cheesecake index for package 'Durus-3.1.tar.gz' 
    355  
    356  [cheesecake:console] Starting computation of INSTALLABILITY index (max. points = 140) 
    357  index_pypi_download .....................  45 (downloaded package Durus-3.1.tar.gz following 1 link from PyPI) 
    358  index_unpack ............................  25 (package untar-ed successfully) 
    359  index_unpack_dir ........................  15 (unpack directory is Durus-3.1 as expected) 
    360  index_install ...........................  50 (package installed in /tmp/cheesecake_sandbox/tmp_install_Durus-3.1) 
    361  --------------------------------------------- 
    362  INSTALLABILITY INDEX (ABSOLUTE) ......... 135 
    363  INSTALLABILITY INDEX (RELATIVE) .........  96 (135 out of a maximum of 140 points is 96%) 
    364  
    365  [cheesecake:console] Starting computation of DOCUMENTATION index (max. points = 415) 
    366  index_file_announce .....................   0 (file not found) 
    367  index_file_changelog ....................   0 (file not found) 
    368  index_file_ez_setup.py ..................   0 (file not found) 
    369  index_file_faq ..........................  10 (file found) 
    370  index_file_install ......................  10 (file found) 
    371  index_file_license ......................  15 (critical file found) 
    372  index_file_news .........................   0 (file not found) 
    373  index_file_readme .......................  15 (critical file found) 
    374  index_file_setup.py .....................  15 (critical file found) 
    375  index_file_thanks .......................   0 (file not found) 
    376  index_file_todo .........................   0 (file not found) 
    377  index_dir_demo ..........................   0 (directory not found) 
    378  index_dir_doc ...........................  25 (critical directory found) 
    379  index_dir_example .......................   0 (directory not found) 
    380  index_dir_test ..........................  25 (critical directory found) 
    381  index_docstrings ........................  42 (found 104/249=41.77% modules/classes/methods/functions with docstrings) 
    382  --------------------------------------------- 
    383  DOCUMENTATION INDEX (ABSOLUTE) .......... 157 
    384  DOCUMENTATION INDEX (RELATIVE) ..........  37 (157 out of a maximum of 415 points is 37%) 
    385   
    386  [cheesecake:console] Starting computation of CODE KWALITEE index (max. points = 100) 
    387  index_pylint ............................  64 (average score is 6.30 out of 10) 
    388  --------------------------------------------- 
    389  CODE KWALITEE INDEX (ABSOLUTE) ..........  64 
    390  CODE KWALITEE INDEX (RELATIVE) ..........  64 (64 out of a maximum of 100 points is 64%) 
    391   
    392  ============================================= 
    393  OVERALL CHEESECAKE INDEX (ABSOLUTE) ..... 356 
    394  OVERALL CHEESECAKE INDEX (RELATIVE) .....  64 (356 out of a maximum of 555 points is 64%) 
    395  
     203    $ python cheesecake_index -n Durus 
     204    py_pi_download .........................  50  (downloaded package Durus-3.4.1.tar.gz following 1 link from http://www.mems-exchange.org/software/durus/Durus-3.4.1.tar.gz) 
     205    unpack .................................  25  (package unpacked successfully) 
     206    unpack_dir .............................  15  (unpack directory is Durus-3.4.1 as expected) 
     207    setup.py ...............................  25  (setup.py found) 
     208    install ................................  50  (package installed in /tmp/cheesecakebJ2JTZ/tmp_install_Durus-3.4.1) 
     209    generated_files ........................   0  (0 .pyc and 0 .pyo files found) 
     210    --------------------------------------------- 
     211    INSTALLABILITY INDEX (ABSOLUTE) ........ 165 
     212    INSTALLABILITY INDEX (RELATIVE) ........ 100  (165 out of a maximum of 165 points is 100%) 
     213     
     214    required_files ......................... 150  (4 files and 2 required directories found) 
     215    docstrings .............................  33  (found 121/369=32.79% objects with docstrings) 
     216    formatted_docstrings ...................   0  (found 6/369=1.63% objects with formatted docstrings) 
     217    --------------------------------------------- 
     218    DOCUMENTATION INDEX (ABSOLUTE) ......... 183 
     219    DOCUMENTATION INDEX (RELATIVE) .........  53  (183 out of a maximum of 350 points is 53%) 
     220     
     221    pylint .................................  33  (pylint score was 6.59 out of 10) 
     222    use_test_framework .....................  30  (use one or more of known test frameworks) 
     223    --------------------------------------------- 
     224    CODE KWALITEE INDEX (ABSOLUTE) .........  63 
     225    CODE KWALITEE INDEX (RELATIVE) .........  79  (63 out of a maximum of 80 points is 79%) 
     226     
     227     
     228    ============================================= 
     229    OVERALL CHEESECAKE INDEX (ABSOLUTE) .... 411 
     230    OVERALL CHEESECAKE INDEX (RELATIVE) ....  69  (411 out of a maximum of 595 points is 69%) 
     231     
    396232Future plans 
    397233------------ 
    …… 
    403239by the Cheesecake metrics. 
    404240 
    405 .. footer:: Last modified 2006-05-25 by `Michal Kwiatkowski <http://joker.linuxstuff.pl>`_. 
     241.. footer:: Last modified 2006-07-30 by `Michal Kwiatkowski <http://joker.linuxstuff.pl>`_.