Toolshed: types
: XList
¶
Import XList
¶
from Naked.toolshed.types import XList
Import XList
from C Module¶
from Naked.toolshed.c.types import XList
The C module must be compiled before you import it. See the naked build documentation for more information.
Description¶
The XList
class is an extension of the Python list type. You can use all built-in Python list methods with it. It extends the built-in Python list type with operator overloads, metadata definitions on instantiation, preservation of metadata on conversion to other types (with included XList methods), and a number of additional list methods.
The XList
supports equality testing based upon both the values of the list items as well as the supplemental XList metadata (if included). You can use the ==
and !=
operators to perform this testing (or alternatively, the XList.equals()
method).
-
class
Naked.toolshed.types.
XList
(the_list[, attribute_dictionary])¶ A
XList
is instantiated with any Python sequence type, including sets, tuples, and other lists. You have the option to include a Python dictionary as a second parameter to include additional metadata. The metadata are stored as attributes on theXList
with dictionary keys mapped to attribute names and dictionary values mapped to the corresponding attribute values.Parameters: - the_list (list) – the data that are used to create an instance of a
XList
list. This can be of any Python sequence type, including sets, tuples, and other lists. - attribute_dictionary (dictionary) – (optional) a Python dictionary that is used to define the attributes of a new instance of a
XList
. Key names are mapped to attribute names and their corresponding values are mapped to the attribute values.
Overloaded Operators
-
__add__
(*other_lists)¶ The
+
operator is overloaded to extend theXList
with one or more otherXLists
or lists. TheXList
must be the left sided operand in your statement to use this overloaded operator. When used with a Python list, theXList
is extended with the items in the list. When used with anotherXList
, the originalXList
is extended with the items and the attributes in the otherXList
. The right sidedXList
operand attribute values take precendence when the same attribute is included in bothXLists
.Parameters: other_lists (list) – one or more Python lists or XList
(i.e. can add multiple XLists: xl = xl1 + xl2 + xl3)Returns: (XList) returns the original XList extended with data in the *other_lists
as defined above
-
__iadd__
(other_list)¶ The
+=
operator is overloaded to extend theXList
with anotherXList
or list. TheXList
must be the left sided operand in your statement to use this overloaded operator. When used with a Python list, theXList
is extended with the items in the list. When used with anotherXList
, the originalXList
is extended with the items and the attributes in the otherXList
. The right sidedXList
operand attribute values take precendence when the same attribute is included in bothXLists
.Parameters: other_list (list) – a Python list or XList
Returns: (XList) returns the original XList extended with data in the other_list
as defined above
-
__eq__
(other_list)¶ The
==
operator is overloaded to perform equality testing as defined for theequals()
method below.Returns: (boolean) True
= conditions for equality are met;False
= conditions for equality are not met
-
__neq__
(other_dictionary)¶ The
!=
operator is overloaded to return the negation of the test for equality as it is defined in theequals()
method below.Returns: (boolean) True
= conditions for equality are not met;False
= conditions for equality are met
XList Methods
-
conditional_map_to_items
(conditional_func, map_func)¶ Map a function
map_func
to items in aXList
that meet aTrue
condition in the function,conditional_func
. Seemap_to_items()
if you would like to map a function to every item in the list.Parameters: - conditional_func (function) – a function that returns a boolean value where
True
means that themap_func
should be executed on the item - map_func (function) – the function that is conditionally executed with the
XList
item as a parameter. The return value is used as the replacement value in theXList
. If the function does not return a value, the item is replaced withNone
.
Returns: (XList) returns a
XList
with the above modifications- conditional_func (function) – a function that returns a boolean value where
-
count_duplicates
()¶ Count the number of duplicate items in the
XList
. Seeremove_duplicates()
to remove the duplicated items.Returns: (int) returns the count of duplicate items
-
difference
(test_list)¶ Return a set with the items in the
XList
that are not contained in the parametertest_list
. Also seeintersection()
.Parameters: test_list (list) – a XList
or list that is to be tested againstReturns: (set) returns a Python set
-
equals
(other_object)¶ The
equals()
method performs equality testing between aXList
and another object. The==
operator can also be used to perform this test between the left (XList
) and right (other_object
) sided operands. Equality testing is defined by meeting the criteria: (1) the type of theXList
and theother_object
are the same; (2) the list item values in theXList
and theother_object
are the same; (3) the attribute metadata (if present) are the same in theXList
and theother_object
.Parameters: other_object (object) – an object that is to be tested for equality Returns: (boolean) True
= conditions for equality are met;False
= conditions for equality are not met
-
intersection
(test_list)¶ Return a set with the items in
XList
that are also contained in the parametertest_list
. Also seedifference()
.Parameters: test_list (list) – a XList
or list that is to be tested againstReturns: (set) returns a Python set
-
join
(delimiter)¶ Joins the string items in a
XList
with thedelimiter
string between eachXList
item and returns a string (or unicode) type.Parameters: delimiter (string) – the character or string to use as the delimiter between the items in the XList
that are joinedReturns: (string) returns a string or unicode type depending upon the types of the XList
items, thedelimiter
character or string, and the Python interpreter version.
-
map_to_items
(map_func)¶ Map a function to every item in the
XList
. To conditionally map a function toXList
items (based upon conditions in a second function), seeconditional_map_to_items()
.Parameters: map_func (function) – the function that will take each item as a parameter and return the value for the replacement in the XList
Returns: item and function dependent type. Items will be assigned a value of None
if there is no return value from the function
-
max
()¶ Returns the maximum item value in the
XList
. Also seemin()
.Returns: numeric type, dependent upon the type of the XList
items
-
min
()¶ Returns the minimum item value in the
XList
. Also seemax()
.Returns: numeric type, dependent upon the type of the XList
items
-
postfix
(after_string)¶ Appends a character or string suffix to each item in the
XList
. Also seeprefix()
andsurround()
.Parameters: after_string (string) – the character or string to append to each XList
itemReturns: (XList) returns a XList
with the above modification to each item
-
prefix
(before_string)¶ Prefixes a character or string to each item in the
XList
. Also seepostfix()
andsurround()
.Parameters: before_string (string) – the character or string to prefix on each item in the XList
Returns: (XList) returns a XList
with the above modification to each item
-
random
()¶ Return a random item from the
XList
. The random selection is performed with the Pythonrandom.choice()
method.Returns: random item from the XList
-
random_sample
(number_items)¶ Return a random sample of items from the
XList
. Random sampling is performed with the Pythonrandom.sample()
method. The number of items in the sample is defined with thenumber_items
parameter. Random sampling is performed without replacement.Parameters: number_items (integer) – the number of items to include in the sample Returns: (list) returns a Python list containing number_items
randomly sampled items from theXList
.
-
remove_duplicates
()¶ Removes the duplicate items in a
XList
and returns theXList
. Seecount_duplicates()
for duplicate counts.Returns: (XList) returns the modified XList
with duplicates removed
-
shuffle
()¶ Randomly shuffles the position of the items in the
XList
Returns: (XList) returns a XList
with the above modification
-
sum
()¶ Returns the sum of the item values in the
XList
. Not defined for non-numeric types.Returns: numeric type, dependent upon the type of the XList
items
-
surround
(first_string[, second_string])¶ Perform prefix and suffix string concatenation to every item in a
XList
. Also seeprefix()
andpostfix()
.Parameters: - first_string (string) – character or string that is concatenated to the beginning of each
XList
item. Ifsecond_string
is not specified, this character or string is also concatentated to the end of eachXList
item. - second_string (string) – (optional) optional second character or string parameter that is appended to each
XList
item. If it is not specified, thefirst_string
is concatenated to the beginning and end of eachXList
item.
Returns: (XList) returns a
XList
with the above modifications to each item- first_string (string) – character or string that is concatenated to the beginning of each
-
wildcard_match
(wildcard)¶ Match items in the
XList
by wildcard value and return a list that contains the matched items.Parameters: wildcard (string) – the wildcard value that is to be used for the match attempt Returns: (list) Python list containing the matched items. If there are no matched items, an empty list is returned. Raises: TypeError
if theXList
contains non-string items
-
multi_wildcard_match
(wildcard_sequence)¶ Match items in the
XList
against more than one wildcard. Items are included in the returned list if they match any of the included wildcards.Parameters: wildcard_sequence (string) – a sequence of wildcards delimited by the |
character (e.g. ‘.py|.pyc’)Returns: (list) Python list containing the matched items. If there are no matched items, an empty list is returned. Raises: TypeError
if theXList
contains non-string items
XList Cast Methods
-
xset
()¶ Cast a
XList
to aXSet
.Returns: (XSet) returns a XSet
with preservation of metadata
-
xfset
()¶ Cast a
XList
to aXFSet
.Returns: (XFSet) returns a XFSet
with preservation of metadata
-
xtuple
()¶ Cast a
XList
to aXTuple
.Returns: (XTuple) returns a XTuple
with preservation of metadata
- the_list (list) – the data that are used to create an instance of a
Examples¶
Create a New Instance of XList, No Metadata
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'])
Create a New Instance of XList, With Metadata
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'listtype': 'orderlist'})
Access XList Item
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'listtype': 'orderlist'})
print(xl[0]) # prints 'first'
Access XList Attribute
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'listtype': 'orderlist'})
print(xl.listtype) # prints 'orderlist'
Compare XList, Different List Items
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
xl2 = XList(['different', 'second', 'third'], {'type': 'orderlist'})
print(xl == xl2) # prints False
Compare XList, Different Attribute Metadata
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
xl2 = XList(['first', 'second', 'third'], {'type': 'another_orderlist'})
print(xl == xl2) # prints False
Extend the XList with Another List
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
a_list = ['fourth', 'fifth']
xl2 = xl + a_list
print(xl2) # prints ['first', 'second', 'third', 'fourth', 'fifth']
print(xl2.type) # prints 'orderlist'
Extend the XList with Another List, Alternate Approach with += Overload
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
a_list = ['fourth', 'fifth']
xl += a_list
print(xl) # prints ['first', 'second', 'third', 'fourth', 'fifth']
print(xl.type) # prints 'orderlist'
Comma Delimited String from XList
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
cd_string = xl.join(',')
print(cd_string) # prints 'first,second,third'
Wrap with Quotes
from Naked.toolshed.types import XList
xl = XList(['first', 'second', 'third'], {'type': 'orderlist'})
quote_list = xl.surround('"')
print(quote_list) # prints ['"first"', '"second"', '"third"']
Wrap with HTML Tags
from Naked.toolshed.types import XList
xl = XList(['paragraph one', 'paragraph two', 'paragraph three'], {'type': 'orderlist'})
tag_list = xl.surround('<p class="naked">', '</p>')
for x in tag_list:
print(x)
# prints:
# '<p class="naked">paragraph one</p>'
# '<p class="naked">paragraph two</p>'
# '<p class="naked">paragraph three</p>'
Conditional Mapping of a Function to XList Items
from Naked.toolshed.types import XList
def true_a(xlist_item):
return xlist_item.startswith('a')
def cap_val(xlist_item):
return xlist_item.upper()
xl = XList(['another', 'one', 'many'], {'type': 'orderlist'})
new_list = xl.conditional_map_to_items(true_a, cap_val)
print(new_list) # prints ['ANOTHER', 'one', 'many']
Multiple Wildcard Match
from Naked.toolshed.types import XList
xl = XList(['one', 'two', 'three'], {'type': 'orderlist'})
print(xl.multi_wildcard_match('o*|*hre*')) # prints ['one', 'three']