The reference_length is just the number of bases in a given read that are mapped. This completely ignores any mates and how whatever the aligner is deciding to call the length of the sequenced fragment (i.e., the TLEN field in the SAM/BAM/CRAM file). The template_length is then whatever the TLEN value is in the SAM/BAM/CRAM file. For your example where the values are similar you have cases where the mates are overlapping. For cases where the TLEN is much smaller, it's likely that the reads overlap in a way that the aligner didn't expect:

  <---------------- R1
                -----------------> R2

For the third case, there's just a larger fragment size.

Take for example the following fake reads:

@HD     VN:1.4  SO:coordinate
@SQ     SN:1    LN:195471971
r1      97      1       1       255     50M     =       100     150     *       *
r1      145     1       100     255     50M     =       1       -150    *       *
r2      145     1       200     255     50M     =       245     10      *       *
r2      97      1       245     255     50M     =       200     -10     *       *
r3      97      1       300     255     50M     =       500     250     *       *
r3      145     1       500     255     50M     =       300     -250    *       *

Then in python:

>>> import pysam
>>> bam = pysam.AlignmentFile("foo.bam")
>>> bam = pysam.AlignmentFile("foo.bam")
>>> for b in bam:
...     print("{}\t{}".format(b.template_length, b.reference_length))
... 
150 50
-150    50
10  50
-10 50
250 50
-250    50