Skip to content

Commit

Permalink
Merge pull request #36 from Ousret/develop
Browse files Browse the repository at this point in the history 
Prepare next-minor
  • Loading branch information
@Ousret
Ousret authored May 24, 2020
2 parents c35a211 + 18b882e commit fa3a1c8
Show file tree
Hide file tree
Showing 4 changed files with 264 additions and 56 deletions.
187 changes: 159 additions & 28 deletions docs/APIs/models.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,37 @@ This method will restrict type entropy by always returning a List[Header] instea

## Classes

### Class `Attributes` {#kiss_headers.models.Attributes}


> `class Attributes(members: List[str])`
Dedicated class to handle attributes within a Header. Wrap an AttributeBag and offer methods to manipulate it
with ease.
Store advanced info on attributes, case insensitive on keys and keep attrs ordering.

#### Instance variables

##### Variable `last_index` {#kiss_headers.models.Attributes.last_index}

Simply output the latest index used in attributes. Index start from zero.

#### Methods

##### Method `insert` {#kiss_headers.models.Attributes.insert}

> `def insert(self, key: str, value: Union[str, NoneType], index: Union[int, NoneType] = None) -> NoneType`
##### Method `keys` {#kiss_headers.models.Attributes.keys}

> `def keys(self) -> List[str]`
This method return a list of attribute name that have at least one value associated to them.

##### Method `remove` {#kiss_headers.models.Attributes.remove}

> `def remove(self, key: str, index: Union[int, NoneType] = None, with_value: Union[bool, NoneType] = None) -> NoneType`
### Class `Header` {#kiss_headers.models.Header}

> `class Header(name: str, content: str)`
Expand All @@ -31,7 +62,7 @@ Object representation of a single Header.

##### Variable `attrs` {#kiss_headers.models.Header.attrs}

List of members or attributes found in provided content.
List of members or attributes found in provided content. This list is ordered and normalized.
eg. Content-Type: application/json; charset=utf-8; format=origin
Would output : ['application/json', 'charset', 'format']

Expand All @@ -43,7 +74,7 @@ Retrieve comments in header content.

##### Variable `content` {#kiss_headers.models.Header.content}

Output associated content to header as it was captured initially.
Output associated content to the header as it was captured initially.
```python
header = Header("ETag", '"33a64df551425fcc55e4d42a148795d9f25f89d4"')
header.content
Expand All @@ -54,7 +85,7 @@ header.content

##### Variable `name` {#kiss_headers.models.Header.name}

Output the original header name as it was captured initially
Output the original header name as it was captured initially.


##### Variable `normalized_name` {#kiss_headers.models.Header.normalized_name}
Expand All @@ -64,16 +95,22 @@ Output header name but normalized, lower case and '-' character become '_'.

##### Variable `pretty_name` {#kiss_headers.models.Header.pretty_name}

Output a prettified name of the header. First letter capitalized of each word.
Output a prettified name of the header. The first letter capitalized on each word.


##### Variable `unfolded_content` {#kiss_headers.models.Header.unfolded_content}

Output unfolded associated content to header. Meaning that every LF + n space(s) would be properly
Output unfolded associated content to the header. Meaning that every LF + n space(s) would be properly
replaced.


##### Variable `valued_attrs` {#kiss_headers.models.Header.valued_attrs}

List of distinct attributes that have at least one value associated with them. This list is ordered and normalized.
This property could have been written under the keys() method, but implementing it would interfere with dict()
cast and the __iter__() method.
eg. Content-Type: application/json; charset=utf-8; format=origin
Would output : ['charset', 'format']

#### Methods

Expand All @@ -82,12 +119,9 @@ replaced.
##### Method `get` {#kiss_headers.models.Header.get}




> `def get(self, attr: str) -> Union[str, List[str], NoneType]`

Retrieve associated value of an attribute.
Retrieve the associated value of an attribute.
```python
header = Header("Content-Type", "application/json; charset=UTF-8; format=flowed")
header.charset
Expand All @@ -110,7 +144,7 @@ header.format
> `def has(self, attr: str) -> bool`

Safely check is current header has an attribute or adjective in it.
Safely check if the current header has an attribute or adjective in it.


##### Method `has_many` {#kiss_headers.models.Header.has_many}
Expand All @@ -132,16 +166,48 @@ False



##### Method `insert` {#kiss_headers.models.Header.insert}




> `def insert(self, _Header__index: int, *_Header__members: str, **_Header__attributes: Union[str, NoneType]) -> NoneType`

This method allows you to properly insert attributes into a Header instance.


##### Method `pop` {#kiss_headers.models.Header.pop}




> `def pop(self) -> Tuple[str, Union[str, List[str], NoneType]]`

Permit to pop an element from a Header with a given index.
```python
header = Header("X", "a; b=k; h; h; z=0; y=000")
header.pop(1)
('b', 'k')
header.pop()
('y', '000')
header.pop('z')
('z', '0')
```



### Class `Headers` {#kiss_headers.models.Headers}



> `class Headers(*headers: Union[List[kiss_headers.models.Header], kiss_headers.models.Header])`

Object oriented representation for Headers. Contains a list of Header with some level of abstraction.
Combine advantages of dict, CaseInsensibleDict and native objects.
Headers does not inherit of the Mapping type, but it does borrow some concept from it.
Object-oriented representation for Headers. Contains a list of Header with some level of abstraction.
Combine advantages of dict, CaseInsensibleDict, list, multi-dict, and native objects.
Headers do not inherit the Mapping type, but it does borrow some concepts from it.

:param headers: Initial list of header. Can be empty.

Expand All @@ -164,7 +230,7 @@ Headers does not inherit of the Mapping type, but it does borrow some concept fr
> `def get(self, header: str) -> Union[kiss_headers.models.Header, List[kiss_headers.models.Header], NoneType]`

Retrieve header from headers if exists
Retrieve header from headers if exists.


##### Method `has` {#kiss_headers.models.Headers.has}
Expand All @@ -175,7 +241,7 @@ Retrieve header from headers if exists
> `def has(self, header: str) -> bool`

Safely check if header name is in headers
Safely check if header name is in headers.


##### Method `has_many` {#kiss_headers.models.Headers.has_many}
Expand All @@ -186,7 +252,7 @@ Safely check if header name is in headers
> `def has_many(self, name: str) -> bool`

Determine if an header name has multiple entries in Headers. Detect OneToMany entries.
Determine if a header name has multiple entries in Headers. Detect OneToMany entries.
```python
headers = Header("A", "0") + Header("A", "1") + Header("B", "sad")
headers.has_many("a")
Expand All @@ -197,6 +263,48 @@ False



##### Method `index` {#kiss_headers.models.Headers.index}




> `def index(self, _Headers__value: Union[kiss_headers.models.Header, str]) -> int`

Search for the first appearance of an header based on its name or instance in Headers.
Same method signature as list().index().
Raises IndexError if not found.
```python
headers = Header("A", "hello") + Header("B", "world") + Header("C", "funny; riddle")
headers.index("A")
0
headers.index("A", 1)
Traceback (most recent call last):
...
IndexError: Value 'A' is not present within Headers.
headers.index("A", 0, 1)
0
headers.index("C")
2
headers.index(headers[0])
0
headers.index(headers[1])
1
```



##### Method `insert` {#kiss_headers.models.Headers.insert}




> `def insert(self, _Headers__index: int, _Headers__header: kiss_headers.models.Header) -> NoneType`

Insert header before the given index.


##### Method `items` {#kiss_headers.models.Headers.items}


Expand All @@ -205,8 +313,8 @@ False
> `def items(self) -> List[Tuple[str, str]]`

Provide an iterator witch each entry contain a tuple of header name and content.
This wont return a ItemView.
Provide a list witch each entry contains a tuple of header name and content.
This won't return an ItemView as Headers does not inherit from Mapping.
```python
headers = Header("X-Hello-World", "1") + Header("Content-Type", "happiness=True") + Header("Content-Type", "happiness=False")
headers.items()
Expand All @@ -224,7 +332,8 @@ headers.items()

Return a list of distinct header name set in headers.
Be aware that it wont return a typing.KeysView
Be aware that it won't return a typing.KeysView.
Also this method allows you to create a case sensitive dict.


##### Method `pop` {#kiss_headers.models.Headers.pop}
Expand All @@ -235,7 +344,30 @@ Be aware that it wont return a typing.KeysView
> `def pop(self) -> Union[kiss_headers.models.Header, List[kiss_headers.models.Header]]`

Pop header from headers. By default the last one.
Pop header instance(s) from headers. By default the last one. Accept index as integer or header name.
If you pass a header name, it will pop from Headers every entry named likewise.
```python
headers = Header("A", "hello") + Header("B", "world") + Header("C", "funny; riddle")
header = headers.pop()
repr(header)
'C: funny; riddle'
headers = Header("A", "hello") + Header("B", "world") + Header("C", "funny; riddle")
header = headers.pop(1)
repr(header)
'B: world'
header = headers.pop("A")
repr(header)
'A: hello'
headers = Header("A", "hello") + Header("B", "world") + Header("C", "funny; riddle") + Header("B", "ending")
headers = headers.pop("B")
len(headers)
2
headers[0].name
'B'
(str(headers[0]), str(headers[1]))
('world', 'ending')
```



##### Method `popitem` {#kiss_headers.models.Headers.popitem}
Expand All @@ -246,7 +378,7 @@ Pop header from headers. By default the last one.
> `def popitem(self) -> Tuple[str, str]`

Pop last header as a tuple (header name, header content).
Pop the last header as a tuple (header name, header content).


##### Method `to_dict` {#kiss_headers.models.Headers.to_dict}
Expand All @@ -258,8 +390,9 @@ Pop last header as a tuple (header name, header content).

Provide a CaseInsensitiveDict output of current headers. This output type has been borrowed from psf/requests.
If one header appear multiple times, if would be concatenated into the same value, separated by comma.
Be aware that this repr could lead to mistake.
If one header appears multiple times, it would be concatenated into the same value, separated by a comma.
Be aware that this repr could lead to a mistake. You could also cast a Headers instance to dict() to get a
case sensitive one. see method keys().


##### Method `to_json` {#kiss_headers.models.Headers.to_json}
Expand All @@ -270,7 +403,7 @@ Be aware that this repr could lead to mistake.
> `def to_json(self) -> str`

Provide a JSON representation of Headers
Provide a JSON representation of Headers. JSON is by definition a string.


##### Method `values` {#kiss_headers.models.Headers.values}
Expand All @@ -281,9 +414,7 @@ Provide a JSON representation of Headers
> `def values(self) -> NotImplemented`

I choose not to implement values() on Headers as it would bring more confusion..
Either we make it the same len as keys() or we don't. Either way don't please me. Hope to ear from the
I choose not to implement values() on Headers as it would bring more confusion...
Either we make it the same len as keys() or we don't. Either way don't please me. Hope to hear from the
community about this.



Loading

0 comments on commit fa3a1c8

Please sign in to comment.