Skip to content

Commit b3b2dbc

Browse files
hanke0hanke0
committed
Documentation improvement
1 parent 47b8c5d commit b3b2dbc

8 files changed

Lines changed: 448 additions & 202 deletions

File tree

‎Makefile‎

Lines changed: 28 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,18 @@
1+
PYTHON ?= python
2+
13
.DEFAULT_GOAL := build
24

5+
HELP_LINE=" \033[36m%-30s\033[0m %s\n"
36
# Absolutely awesome: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
47
.PHONY: help
58
help:
6-
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
9+
@echo "CTools Makefile"
10+
@echo
11+
@echo "Variables:"
12+
@printf $(HELP_LINE) PYTHON "python executable path"
13+
@echo
14+
@echo "Commands:"
15+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf $(HELP_LINE), $$1, $$2}'
716

817
.PHONY: dist
918
dist: clean ## Build dists
@@ -12,16 +21,16 @@ dist: clean ## Build dists
1221

1322
.PHONY: clean-cache
1423
clean-cache:
15-
find -name *.egg-info -exec rm -rf {} +
16-
find -name *.pyc -exec rm -rf {} +
17-
find -name *.pyo -exec rm -rf {} +
18-
find -name *.so -exec rm -rf {} +
19-
find -name *.pyd -exec rm -rf {} +
24+
@find -name *.egg-info -exec rm -rf {} +
25+
@find -name *.pyc -exec rm -rf {} +
26+
@find -name *.pyo -exec rm -rf {} +
27+
@find -name *.so -exec rm -rf {} +
28+
@find -name *.pyd -exec rm -rf {} +
2029

2130
.PHONY: clean
2231
clean: clean-cache ## Clean cache, include dist
23-
rm -rf dist
24-
rm -rf build
32+
@rm -rf dist
33+
@rm -rf build
2534

2635
.PHONY: format fmt
2736
format fmt: ## Format code
@@ -31,7 +40,7 @@ format fmt: ## Format code
3140

3241
.PHONY: benchmark
3342
benchmark: ## Run benchmark
34-
@$(CURDIR)/tools/runbenchmark.py benchmarks/
43+
@$(PYTHON) $(CURDIR)/tools/runbenchmark.py benchmarks/
3544

3645
.PHONY: pypi-test
3746
pypi-test:
@@ -42,21 +51,22 @@ pypi:
4251
@$(CURDIR)/tools/upload-pypi.sh
4352

4453
.PHONY: build
45-
build: clean ## build package
46-
@python setup.py build_ext --inplace
54+
build: clean ## Build package
55+
@$(PYTHON) setup.py build_ext --inplace
4756

4857
.PHONY: test
49-
test: ## running test
50-
@$(CURDIR)/tools/runtest.py -s ./tests -p .
58+
test: ## Run unit tests
59+
@$(PYTHON) $(CURDIR)/tools/runtest.py -s ./tests -p .
5160

5261
.PHONY: check-doc
53-
check-doc: ## check documentation
54-
python $(CURDIR)/tools/checkdoc.py
62+
check-doc: ## Check documentation
63+
$(PYTHON) $(CURDIR)/tools/checkdoc.py 'ctools.**'
5564

5665
.PHONY: doc
57-
doc: ## generate api doc
66+
doc: ## Build documentation
5867
cd $(CURDIR)/docs && make clean && make html
5968

69+
PY_INCLUDE=$(shell $(PYTHON) -c "from sysconfig import get_paths as gp; print(gp()['include'])")
6070
.PHONY: check
61-
check:
62-
clang-tidy src/* -- -I/usr/include/python3.7m/
71+
check: ## Clang-tidy codes
72+
clang-tidy src/* -- -I "$(PY_INCLUDE)"

‎src/cachemap.c‎

Lines changed: 42 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ limitations under the License.
1515
*/
1616

1717
#include "core.h"
18+
#include "pydoc.h"
1819

1920
#include <Python.h>
2021
#include <time.h>
@@ -690,11 +691,11 @@ static PyMethodDef CacheMap_methods[] = {
690691
{"set_capacity", (PyCFunction)CacheMap_set_capacity, METH_O,
691692
"set_capacity(capacity, /)\n--\n\n Reset capacity of cache."},
692693
{"hit_info", (PyCFunction)CacheMap_hit_info, METH_NOARGS,
693-
"Return capacity, hits, and misses count"},
694+
"hit_info()\n--\n\nReturn capacity, hits, and misses count."},
694695
{"next_evict_key", (PyCFunction)CacheMap_NextEvictKey, METH_NOARGS,
695-
"Return the most unused key."},
696+
"next_evict_key()\n--\n\nReturn the most unused key."},
696697
{"get", (PyCFunction)CacheMap_get, METH_VARARGS | METH_KEYWORDS,
697-
"get(key, default=None)\n--\n\nGet item from cache"},
698+
"get(key, default=None)\n--\n\nGet item from cache."},
698699
{"setdefault", (PyCFunction)CacheMap_setdefault,
699700
METH_VARARGS | METH_KEYWORDS,
700701
"setdefault(key, default=None, /)\n--\n\nGet item in cache, if key not "
@@ -703,19 +704,29 @@ static PyMethodDef CacheMap_methods[] = {
703704
"pop(key, default=None, /)\n--\n\nPop an item from cache, if key not "
704705
"exists return default."},
705706
{"popitem", (PyCFunction)CacheMap_popitem, METH_NOARGS,
706-
"popitem()\n--\n\nremove and return some (key, value) pair"
707-
"as a 2-tuple; but raise KeyError if mapping is empty"},
708-
{"keys", (PyCFunction)CacheMap_keys, METH_NOARGS, "Iter keys."},
709-
{"values", (PyCFunction)CacheMap_values, METH_NOARGS, "Iter values."},
707+
"popitem()\n--\n\nRemove and return some (key, value) pair"
708+
"as a 2-tuple; but raise KeyError if mapping is empty."},
709+
{"keys", (PyCFunction)CacheMap_keys, METH_NOARGS,
710+
"keys()\n--\n\nIter keys."},
711+
{"values", (PyCFunction)CacheMap_values, METH_NOARGS,
712+
"values()\n--\n\nIter values."},
710713
{"items", (PyCFunction)CacheMap_items, METH_NOARGS,
711-
"Iter keys and values."},
714+
"items()\n--\n\nIter keys and values."},
712715
{"update", (PyCFunction)CacheMap_update, METH_VARARGS | METH_KEYWORDS,
713716
"update(map, /)\n--\n\nUpdate item to cache. Unlike dict.update, only "
714717
"accept a dict object."},
715-
{"clear", (PyCFunction)CacheMap_clear, METH_NOARGS, "clean cache"},
716-
{"setnx", (PyCFunction)CacheMap_setnx, METH_VARARGS | METH_KEYWORDS,
717-
"setnx(key, fn, /)\n--\n\nLike setdefault but accept a callable "
718-
"object which takes key as only one argument"},
718+
{
719+
"clear",
720+
(PyCFunction)CacheMap_clear,
721+
METH_NOARGS,
722+
"clear()\n--\n\nClean cache.",
723+
},
724+
{
725+
"setnx",
726+
(PyCFunction)CacheMap_setnx,
727+
METH_VARARGS | METH_KEYWORDS,
728+
USUAL_SETNX_METHOD_DOC,
729+
},
719730
{"_storage", (PyCFunction)CacheMap__storage, METH_NOARGS, NULL},
720731
{NULL, NULL, 0, NULL} /* Sentinel */
721732
};
@@ -743,19 +754,25 @@ static PyObject *CacheMap_tp_richcompare(PyObject *self, PyObject *other,
743754
}
744755
}
745756

746-
PyDoc_STRVAR(CacheMap__doc__, "CacheMap(maxsize=None, /)\n\n"
747-
"A fast LFU (least frequently used) mapping.\n\n"
748-
"Default max size is C ``INT32_MAX``.\n\n"
749-
"Examples\n"
750-
"--------\n"
751-
">>> import ctools\n"
752-
">>> cache = ctools.CacheMap(1)\n"
753-
">>> cache['foo'] = 'bar'\n"
754-
">>> cache['foo']\n"
755-
"'bar'\n"
756-
">>> cache['bar'] = 'foo'\n"
757-
">>> 'foo' in cache\n"
758-
"False\n");
757+
PyDoc_STRVAR(CacheMap__doc__,
758+
"CacheMap(maxsize=None, )\n--\n\n"
759+
"A fast LFU (least frequently used) mapping.\n"
760+
"\n"
761+
"Parameters\n"
762+
"----------\n"
763+
"maxsize : int\n"
764+
" Max size of cache, default is C ``INT32_MAX``.\n"
765+
"\n"
766+
"Examples\n"
767+
"--------\n"
768+
">>> import ctools\n"
769+
">>> cache = ctools.CacheMap(1)\n"
770+
">>> cache['foo'] = 'bar'\n"
771+
">>> cache['foo']\n"
772+
"'bar'\n"
773+
">>> cache['bar'] = 'foo'\n"
774+
">>> 'foo' in cache\n"
775+
"False\n");
759776

760777
static PyTypeObject CacheMap_Type = {
761778
/* clang-format off */

‎src/channel.c‎

Lines changed: 56 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -398,36 +398,38 @@ static PyObject *Channel_size(PyObject *self, PyObject *Py_UNUSED(unused)) {
398398
return PyLong_FromLong(Py_SIZE(self));
399399
}
400400

401-
PyDoc_STRVAR(
402-
Channel_send__doc__,
403-
"send(obj, /)\n--\n\nSend an object to channel. Return False if channel "
404-
"is full.\n"
405-
"\nReturns\n"
406-
"-------\n"
407-
"bool\n"
408-
" Return True if send success else False\n"
409-
"\nRaises\n"
410-
"------\n"
411-
"IndexError\n"
412-
" If the channel is closing for sending");
413-
414-
PyDoc_STRVAR(
415-
Channel_recv__doc__,
416-
"recv()\n--\n\nReceive an object from channel. If nothing in channel, "
417-
"return None and False, else return received and True\n"
418-
"\nReturns\n"
419-
"-------\n"
420-
"o\n"
421-
" Object that received. Return None if no items in channel.\n"
422-
"ok : bool\n"
423-
" Return False if no items in channel else True.\n"
424-
"\nRaises\n"
425-
"------\n"
426-
"IndexError\n"
427-
" If the channel is closing for receive");
401+
PyDoc_STRVAR(Channel_send__doc__, "send(obj, /)\n--\n\n"
402+
"Send an object to channel.\n"
403+
"\n"
404+
"Returns\n"
405+
"-------\n"
406+
"bool\n"
407+
" Return True if send success else False\n"
408+
"\n"
409+
"Raises\n"
410+
"------\n"
411+
"IndexError\n"
412+
" If the channel is closing for sending.\n");
413+
414+
PyDoc_STRVAR(Channel_recv__doc__,
415+
"recv()\n--\n\n"
416+
"Receive an object from channel.\n"
417+
"\n"
418+
"Returns\n"
419+
"-------\n"
420+
"o\n"
421+
" Object that received. Return None if no items in channel.\n"
422+
"ok : bool\n"
423+
" Return False if no items in channel else True.\n"
424+
"\n"
425+
"Raises\n"
426+
"------\n"
427+
"IndexError\n"
428+
" If the channel is closing for receive.\n");
428429

429430
PyDoc_STRVAR(Channel_safe_consume__doc__,
430-
"safe_consume(fn, /)\n--\n\nsafe consume with a callable.\n\n"
431+
"safe_consume(fn, /)\n--\n\n"
432+
"Safe consume with a callable.\n\n"
431433
"Parameters\n"
432434
"----------\n"
433435
"fn : Callable[[Any], bool]\n"
@@ -447,40 +449,46 @@ static PyMethodDef Channel_methods[] = {
447449
"clear",
448450
(PyCFunction)Channel_clear,
449451
METH_NOARGS,
450-
"clear()\n--\n\nClear channel",
452+
"clear()\n--\n\nClear channel.",
451453
},
452454
{"close", (PyCFunction)Channel_close, METH_VARARGS | METH_KEYWORDS,
453-
"close(send=True, recv=True)\n--\n\nclose channel."},
455+
"close(send=True, recv=True)\n--\n\nClose channel."},
454456
{
455457
"safe_consume",
456458
(PyCFunction)Channel_safe_consume,
457459
METH_O,
458460
Channel_safe_consume__doc__,
459461
},
460462
{"sendable", (PyCFunction)Channel_sendable, METH_NOARGS,
461-
"sendable()\n--\n\nchannel is available to send?"},
463+
"sendable()\n--\n\nReturn channel is available to send."},
462464
{"recvable", (PyCFunction)Channel_recvable, METH_NOARGS,
463-
"recvable()\n--\n\nchannel is available to receive?"},
465+
"recvable()\n--\n\nReturn channel is available to receive."},
464466
{"size", (PyCFunction)Channel_size, METH_NOARGS,
465-
"size()\n--\n\nreturn the size of channel."},
467+
"size()\n--\n\nReturn the size of channel."},
466468
{NULL, NULL, 0, NULL} /* Sentinel */
467469
};
468470

469-
PyDoc_STRVAR(Channel_Doc, "Channel(size=None, /)\n\n"
470-
"A channel support sending and safe consuming.\n"
471-
"Default size is C ``MAX_INT32``\n\n"
472-
"Examples\n"
473-
"--------\n"
474-
">>> import ctools\n"
475-
">>> ch = ctools.Channel(1)\n"
476-
">>> ch.send('foo')\n"
477-
"True\n"
478-
">>> ch.send('bar')\n"
479-
"False\n"
480-
">>> ch.recv()\n"
481-
"('foo', True)\n"
482-
">>> ch.recv()\n"
483-
"(None, False)");
471+
PyDoc_STRVAR(Channel_Doc,
472+
"Channel(size=None, /)\n--\n\n"
473+
"A channel support sending and safe consuming.\n"
474+
"\n"
475+
"Parameters\n"
476+
"----------\n"
477+
"size : int, optional\n"
478+
" The max size of channel, default to C ``MAX_INT32``.\n"
479+
"\n"
480+
"Examples\n"
481+
"--------\n"
482+
">>> import ctools\n"
483+
">>> ch = ctools.Channel(1)\n"
484+
">>> ch.send('foo')\n"
485+
"True\n"
486+
">>> ch.send('bar')\n"
487+
"False\n"
488+
">>> ch.recv()\n"
489+
"('foo', True)\n"
490+
">>> ch.recv()\n"
491+
"(None, False)\n");
484492

485493
static PyTypeObject Channel_Type = {
486494
/* clang-format off */

0 commit comments

Comments
 (0)