عرض مصدر Python/itertools/groupby

<noinclude>{{DISPLAYTITLE:الدالة <code>itertools.groupby()‎</code> في بايثون}}</noinclude>
تعيد الدّالة <code>itertools.groupby()‎</code> مُكرّرًا يُعيد مفاتيح مُتسلسلة ومجموعات (groups) تنتمي إلى هذه المفاتيح من الكائن القابل للتّكرار المعطى.

العمليّة التي تقوم بها الدّالة مُشابهة لكيفيّة عمل المُرشّح <code>uniq</code> في أنظمة Unix. إذ تُولّد نقطة توقّف (break) أو مجموعة جديدة في كلّ مرّة تتغيّر فيها قيمة الدّالةِ المفتاح (لذا يجب في الغالب ترتيب البيانات باستعمال نفس الدّالة المفتاح). وطريقة العمل هذه تختلف عن طريقة عمل [[SQL/group by|عبارة  <code>GROUP BY</code> في لغة SQL]] التي تجمع العناصر المُشتركة بغضّ النّظر عن ترتيب البيانات.

== البنية العامة ==
<syntaxhighlight lang="python3">
itertools.groupby(iterable, key=None)
</syntaxhighlight>

== المعاملات ==
=== <code>iterable</code> ===
الكائن القابل للتّكرار المرغوب تجميع عناصره المُشتركة.

=== <code>key</code> ===
الدّالة التي تُعيد المفتاح الذي سيُستعمل لتجميع عناصر الكائن القابل للتّكرار لكل عنصر من عناصره. إن لم تُمرَّر للمُعامل أيّة قيمة، أو مُرّرت له القيمة <code>None</code>، فستكون قيمة المُعامل <code>key</code> الافتراضيّة عبارة عن دالّة هُويّة (identity function) تُعيد العنصر دون تغيير. يجب على الكائن  <code>iterable</code> أن يكون مُرتّبًا على نفس الدّالة <code>key</code>.

== القيمة المعادة ==
مُكرّر يحتوي على عدّة [[Python/tuple|صفوف]] من عنصرين، العنصر الأول يُمثّل المفتاح، والعنصر الثّاني يُمثّل مجموعة القيم المُرتبطة بالمفتاح.

المجموعة المُعادة تكون مُكرّرًا يُشارك الكائن القابل للتّكرار الداخليّ مع الدّالة  <code>itertools.groupby()‎</code>. ولأنّ المصدر مُشارَك، فستختفي المجموعات كلّما تقدّم الكائن المُعاد (عبر التّكرار). لذا إن كانت البيانات مُهمّة حتى بعد المرور على المجموعات المُعادة، فسيتوجّب عليك تخزينها في قائمة كما يلي:
<syntaxhighlight lang="python3">
groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
    groups.append(list(g))      # خزّن مُكرّر المجموعة كقائمة
    uniquekeys.append(k)
</syntaxhighlight>

== أمثلة ==
المثال التّالي يوضّح كيفيّة عمل هذه الدّالة، نستعمل في هذا المثال إحاطات القوائم (List comprehensions) لإنشاء [[Python/dict|قاموس]] من المجموعات المُعادة، مفاتيح القاموس تكون هي نفسها المفاتيح التي تُعاد من طرف الدّالة <code>key‎</code> (في هذه الحالة العناصر هي نفسها المفاتيح) وتكون قيمة كل مفتاحٍ في القاموس عبارة عن قائمة بالعناصر المتعلّقة بالمفتاح (نحصل على قائمة العناصر بالدّالة <code>[[Python/list|list()‎]]</code>):

<syntaxhighlight lang="python3">
>>> it = 'AAAABBBCCAABBB'
>>> groups = itertools.groupby(it)
>>> [{key: list(group)} for key, group in groups]
[{'A': ['A', 'A', 'A', 'A']},
 {'B': ['B', 'B', 'B']},
 {'C': ['C', 'C']},
 {'A': ['A', 'A']},
 {'B': ['B', 'B', 'B']}]
</syntaxhighlight>

وكما تُلاحظ، فالتّجميع هنا مُتقطّع لأنّ الكائن القابل للتّكرار المُعطى ليس مُرتّبًا. لذا لو رتّبناه بالدّالة <code>[[Python/sorted|sorted()]]</code>‎ قبل أن نُقسّمه إلى مجموعات فسنحصل على مجموعات أشمل دون تكرار للمفتاح:
<syntaxhighlight lang="python3">
>>> it = sorted('AAAABBBCCAABBB')
>>> it
['A', 'A', 'A', 'A', 'A', 'A', 'B', 'B', 'B', 'B', 'B', 'B', 'C', 'C']
>>> groups = itertools.groupby(it)
>>> [{key: list(group)} for key, group in groups]
[{'A': ['A', 'A', 'A', 'A', 'A', 'A']},
 {'B': ['B', 'B', 'B', 'B', 'B', 'B']},
 {'C': ['C', 'C']}
]
</syntaxhighlight>

يُمكن استعمال المُعامل  <code>key‎</code> لتقسيم قاموس أشخاص إلى مجموعات حسب أعمارهم مثلًا، وذلك عبر استعمال [[Python/lambda expressions|تعبير lambda]] يستقبل القاموس ويُعيد عمر الشّخص كما يلي:

<syntaxhighlight lang="python3">
>>> people = [{'name': 'Ahmed', 'age': 18},
...           {'name': 'Mohamed', 'age': 18},
...           {'name': 'Yasser', 'age': 18},
...           {'name': 'Yossuf', 'age': 24},
...           {'name': 'Fatima', 'age': 27}
...           ]
 
>>> grouped_people = itertools.groupby(people, key=lambda x: x['age'])
 
>>> for age, group in grouped_people:
...     print(f'{age}: {list(group)}')
...

18: [{'name': 'Ahmed', 'age': 18},
     {'name': 'Mohamed', 'age': 18},
     {'name': 'Yasser', 'age': 18}]

24: [{'name': 'Yossuf', 'age': 24}]

27: [{'name': 'Fatima', 'age': 27}]
</syntaxhighlight>

== ملاحظات ==
الدّالة مُكافئة لما يلي:
<syntaxhighlight lang="python3">
class groupby:
    # [k for k, g in groupby('AAAABBBCCDAABBB')] --> A B C D A B
    # [list(g) for k, g in groupby('AAAABBBCCD')] --> AAAA BBB CC D
    def __init__(self, iterable, key=None):
        if key is None:
            key = lambda x: x
        self.keyfunc = key
        self.it = iter(iterable)
        self.tgtkey = self.currkey = self.currvalue = object()
    def __iter__(self):
        return self
    def __next__(self):
        while self.currkey == self.tgtkey:
            self.currvalue = next(self.it)    # Exit on StopIteration
            self.currkey = self.keyfunc(self.currvalue)
        self.tgtkey = self.currkey
        return (self.currkey, self._grouper(self.tgtkey))
    def _grouper(self, tgtkey):
        while self.currkey == tgtkey:
            yield self.currvalue
            try:
                self.currvalue = next(self.it)
            except StopIteration:
                return
            self.currkey = self.keyfunc(self.currvalue)
</syntaxhighlight>

== انظر أيضًا ==
* [[Python/iterators|المكرِّرات Iterators في بايثون]].
* [[Python/generators|المولدات Generators في بايثون]].

== مصادر ==
* [https://docs.python.org/3/library/itertools.html#itertools.groupby قسم الدالة itertools.groupby في توثيق Python الرسمي].
[[تصنيف:Python]]
[[تصنيف:Python Function]]
[[تصنيف:Python itertools]]