[Python-checkins] CVS: python/dist/src/Doc/perl python.perl,1.65.2.2,1.65.2.3

[Fred L. Drake]

Update of /projects/cvsroot/python/dist/src/Doc/perl
In directory weyr:/home/fdrake/projects/python/Doc-152p1/perl

Modified Files:
      Tag: release152p1-patches
	python.perl 
Log Message:

Added magic to read from api/refcounts.dat file to generate reference
count information for return values, only for return values of type
PyObject*.

This should take care of *most* questions about reference count
details, but only for the HTML users.

Still needed:  explanations of exceptions to the normal refcounting
rules in the descriptive text of the appropriate functions, and
support for non-HTML formats.


Index: python.perl
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/perl/python.perl,v
retrieving revision 1.65.2.2
retrieving revision 1.65.2.3
diff -C2 -r1.65.2.2 -r1.65.2.3
*** python.perl	1999/10/28 18:44:21	1.65.2.2
--- python.perl	2000/02/01 19:06:40	1.65.2.3
***************
*** 559,562 ****
--- 559,595 ----
  }
  
+ $REFCOUNTS_LOADED = 0;
+ 
+ sub load_refcounts{
+     $REFCOUNTS_LOADED = 1;
+ 
+     use File::Basename;
+     my $myname, $mydir, $myext;
+     ($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
+     chop $mydir;			# remove trailing '/'
+     ($myname, $mydir, $myext) = fileparse($mydir, '\..*');
+     chop $mydir;			# remove trailing '/'
+     $mydir = getcwd() . "$dd$mydir"
+       unless $mydir =~ s|^/|/|;
+     local $_;
+     my $filename = "$mydir${dd}api${dd}refcounts.dat";
+     open(REFCOUNT_FILE, "<$filename") || die "\n$!\n";
+     print "[loading API refcount data]";
+     while (<REFCOUNT_FILE>) {
+         if (/([a-zA-Z0-9_]+):PyObject\*:([a-zA-Z0-9_]*):(0|[-+]1):(.*)$/) {
+             my($func, $param, $count, $comment) = ($1, $2, $3, $4);
+             #print "\n$func($param) --> $count";
+             $REFCOUNTS{"$func:$param"} = $count;
+         }
+     }
+ }
+ 
+ sub get_refcount{
+     my ($func, $param) = @_;
+     load_refcounts()
+         unless $REFCOUNTS_LOADED;
+     return $REFCOUNTS{"$func:$param"};
+ }
+ 
  sub do_env_cfuncdesc{
      local($_) = @_;
***************
*** 568,572 ****
--- 601,619 ----
      $idx =~ s/ \(.*\)//;
      $idx =~ s/\(\)//;		# ????
+     my $result_rc = get_refcount($function_name, '');
+     my $rcinfo = '';
+     if ($result_rc eq '+1') {
+         $rcinfo = '<span class="label">Return value:</span>'
+                   . "\n  <span class=\"value\">New reference.</span>";
+     }
+     elsif ($result_rc eq '0') {
+         $rcinfo = '<span class="label">Return value:</span>'
+                   . "\n  <span class=\"value\">Borrowed reference.</span>";
+     }
+     if ($rcinfo ne '') {
+         $rcinfo = "\n<div class=\"refcount-info\">\n  $rcinfo\n</div>";
+     }
      return "<dl><dt>$return_type <b>$idx</b> (<var>$arg_list</var>)\n<dd>"
+            . $rcinfo
             . $_
             . '</dl>';