2323
2424"""Handle lists of directory paths.
2525
26- These are the path lists that get set as CPPPATH, LIBPATH,
26+ These are the path lists that get set as `` CPPPATH``, `` LIBPATH`` ,
2727etc.) with as much caching of data and efficiency as we can, while
2828still keeping the evaluation delayed so that we Do the Right Thing
2929(almost) regardless of how the variable is specified.
@@ -47,10 +47,10 @@ def node_conv(obj):
4747 """
4848 This is the "string conversion" routine that we have our substitutions
4949 use to return Nodes, not strings. This relies on the fact that an
50- EntryProxy object has a get() method that returns the underlying
51- Node that it wraps, which is a bit of architectural dependence
52- that we might need to break or modify in the future in response to
53- additional requirements.
50+ :class:`~SCons.Node.FS. EntryProxy` object has a `` get()`` method that
51+ returns the underlying Node that it wraps, which is a bit of
52+ architectural dependence that we might need to break or modify in the
53+ future in response to additional requirements.
5454 """
5555 try :
5656 get = obj .get
@@ -64,34 +64,35 @@ def node_conv(obj):
6464 return result
6565
6666class _PathList :
67- """An actual PathList object."""
67+ """An actual PathList object.
6868
69- def __init__ (self , pathlist , split = True ) -> None :
70- """
71- Initializes a PathList object, canonicalizing the input and
72- pre-processing it for quicker substitution later.
69+ Initializes a :class:`PathList` object, canonicalizing the input and
70+ pre-processing it for quicker substitution later.
7371
74- The stored representation of the PathList is a list of tuples
75- containing (type, value), where the "type" is one of the TYPE_*
76- variables defined above. We distinguish between:
72+ The stored representation of the :class:` PathList` is a list of tuples
73+ containing (type, value), where the "type" is one of the `` TYPE_*``
74+ variables defined above. We distinguish between:
7775
78- strings that contain no '$' and therefore need no
79- delayed-evaluation string substitution (we expect that there
80- will be many of these and that we therefore get a pretty
81- big win from avoiding string substitution)
76+ * Strings that contain no ``$`` and therefore need no
77+ delayed-evaluation string substitution (we expect that there
78+ will be many of these and that we therefore get a pretty
79+ big win from avoiding string substitution)
8280
83- strings that contain '$' and therefore need substitution
84- (the hard case is things like ' ${TARGET.dir}/include' ,
85- which require re-evaluation for every target + source)
81+ * Strings that contain ``$`` and therefore need substitution
82+ (the hard case is things like `` ${TARGET.dir}/include`` ,
83+ which require re-evaluation for every target + source)
8684
87- other objects (which may be something like an EntryProxy
88- that needs a method called to return a Node)
85+ * Other objects (which may be something like an
86+ :class:`~SCons.Node.FS.EntryProxy`
87+ that needs a method called to return a Node)
8988
90- Pre-identifying the type of each element in the PathList up-front
91- and storing the type in the list of tuples is intended to reduce
92- the amount of calculation when we actually do the substitution
93- over and over for each target.
94- """
89+ Pre-identifying the type of each element in the :class:`PathList`
90+ up-front and storing the type in the list of tuples is intended to
91+ reduce the amount of calculation when we actually do the substitution
92+ over and over for each target.
93+ """
94+
95+ def __init__ (self , pathlist , split = True ) -> None :
9596 if SCons .Util .is_String (pathlist ):
9697 if split :
9798 pathlist = pathlist .split (os .pathsep )
@@ -152,34 +153,33 @@ class PathListCache:
152153 use the same Memoizer pattern that we use elsewhere to count cache
153154 hits and misses, which is very valuable.
154155
155- Lookup keys in the cache are computed by the _PathList_key() method.
156+ Lookup keys in the cache are computed by the :meth:` _PathList_key` method.
156157 Cache lookup should be quick, so we don't spend cycles canonicalizing
157- all forms of the same lookup key. For example, ' x:y' and ['x',
158- 'y'] logically represent the same list, but we don't bother to
158+ all forms of the same lookup key. For example, `` x:y`` and `` ['x', 'y']``
159+ logically represent the same list, but we don't bother to
159160 split string representations and treat those two equivalently.
160161 (Note, however, that we do, treat lists and tuples the same.)
161162
162163 The main type of duplication we're trying to catch will come from
163164 looking up the same path list from two different clones of the
164- same construction environment. That is, given
165+ same construction environment. That is, given::
165166
166167 env2 = env1.Clone()
167168
168- both env1 and env2 will have the same CPPPATH value, and we can
169- cheaply avoid re-parsing both values of CPPPATH by using the
169+ both `` env1`` and `` env2`` will have the same `` CPPPATH`` value, and we can
170+ cheaply avoid re-parsing both values of `` CPPPATH`` by using the
170171 common value from this cache.
171172 """
172173 def __init__ (self ) -> None :
173174 self ._memo = {}
174175
175176 def _PathList_key (self , pathlist ):
176- """
177- Returns the key for memoization of PathLists.
177+ """Returns the key for memoization of PathLists.
178178
179179 Note that we want this to be pretty quick, so we don't completely
180180 canonicalize all forms of the same list. For example,
181- ' dir1:$ROOT/dir2' and ['$ROOT/dir1', 'dir'] may logically
182- represent the same list if you're executing from $ROOT, but
181+ `` dir1:$ROOT/dir2`` and `` ['$ROOT/dir1', 'dir']`` may logically
182+ represent the same list if you're executing from `` $ROOT`` , but
183183 we're not going to bother splitting strings into path elements,
184184 or massaging strings into Nodes, to identify that equivalence.
185185 We just want to eliminate obvious redundancy from the normal
@@ -191,9 +191,10 @@ def _PathList_key(self, pathlist):
191191
192192 @SCons .Memoize .CountDictCall (_PathList_key )
193193 def PathList (self , pathlist , split = True ):
194- """
195- Returns the cached _PathList object for the specified pathlist,
196- creating and caching a new object as necessary.
194+ """Entry point for getting PathLists.
195+
196+ Returns the cached :class:`_PathList` object for the specified
197+ pathlist, creating and caching a new object as necessary.
197198 """
198199 pathlist = self ._PathList_key (pathlist )
199200 try :
@@ -215,7 +216,8 @@ def PathList(self, pathlist, split=True):
215216
216217PathList = PathListCache ().PathList
217218
218-
219+ # TODO: removing the class object here means Sphinx doesn't pick up its
220+ # docstrings: they're fine for reading here, but are not in API Docs.
219221del PathListCache
220222
221223# Local Variables:
0 commit comments